snapdrift 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 0.9.0 - 2026-09-09
+
+### Fixes
+
+- **Workspace packages now declare their runtime dependency boundaries** (#148).
+  `@snapdrift/adapter-fs` declares `@snapdrift/adapter-report-md`, and an isolated
+  packed-consumer gate imports every workspace package with only its declared
+  local dependency closure. Repository workspaces can no longer mask a missing
+  runtime dependency.
+
+- **Published workspace TypeScript contracts resolve under modern module resolution** (#135, #129). All four `@snapdrift/*` packages expose declarations through their export maps, include signatures for every public runtime export, and correct stale declaration references. Strict declaration checks and isolated packed-package consumer fixtures now run in CI.
+
+- **Snap transport now has enforceable request and operation deadlines** (#150). JSON requests
+  settle stalled headers or bodies within 30 seconds, binary exports within 120 seconds, and each
+  Snap operation shares a 10-minute budget across requests, retries, backoff, and polling. Aborted
+  or otherwise exhausted transport operations now reach the configured `onUnavailable` policy;
+  received 4xx responses remain immediate and non-retryable, while stalled 4xx diagnostics retain
+  their HTTP status with a timeout diagnostic.
+- **Renamed files now retain both paths during route scoping** (#149). The
+  `scope` and `pr-diff` actions include a nonempty `previous_filename` for
+  GitHub rename records, deduplicate the combined paths, and preserve the
+  existing force-run and lookup-fallback behavior (with explicit route ids
+  still taking precedence in `pr-diff`). If GitHub returns its 3,000-record
+  cap, both actions run all configured routes with reason
+  `changed_files_truncated` rather than trust an incomplete list. A file moved
+  out of a watched directory can no longer silently skip its route.
+- **Sanitized route-id collisions are rejected before writing screenshots** (#126). Local capture now fails before browser work, while Snap baseline export validates every source route after downloading the archive and before returning or writing screenshot files. Both paths share the same route-id sanitizer when distinct ids would map to one filename. Existing manifests with duplicate or flattening `imagePath` values also fail closed, including scoped comparisons; rename the conflicting ids and recapture the affected baseline. The published package floors move `@snapdrift/manifest` to 1.3.0 and `@snapdrift/adapter-fs` to 1.1.0 so consumers receive the shared helper.
+- **Baseline lookup failures no longer masquerade as missing artifacts** (#147). The baseline
+  resolver now reports `found`, `missing`, or `error`, fails standalone resolution on API/network/
+  malformed responses, and keeps the PR wrapper's hosted Snap path available while failing local
+  comparisons and local fallbacks when GitHub cannot provide the baseline. The existing intentional
+  first-run skipped summary remains limited to a successful lookup with no non-expired artifact.
+- **Hosted Snap diffs now fail closed on incomplete results** (#146). Hosted comparison now validates `purpose: "diff"`, the persisted run metadata, and expected route/viewport identities, polls until the expected capture set is available, verifies the returned run id and paths, and rejects duplicate, missing, pending, malformed, or invalid captures as `incomplete`. A diffed capture is counted only when both image objects and a finite numeric `diffPct` are present; older results without expected capture identities must be recaptured instead of being treated as clean.
+
+### Changed
+
+- **Standalone baseline resolution now fails on lookup errors** (#147). Consumers orchestrating
+  `actions/resolve-baseline` should handle its `resolution-status` output: `missing` is the
+  intentional first-baseline case, while `error` means the GitHub lookup could not be trusted and
+  fails the action. The PR wrapper keeps hosted Snap comparisons available and reports the status
+  through `baseline-resolution-status`.
+
+### Chore
+
+- **The release workflow now fails when the root dispatcher's immutable pin predates wrapper changes** (#133). The Marketplace `action.yml` pins its inner `baseline` / `pr-diff` refs to an immutable commit SHA, but nothing detected when that pin went stale: between releases every change to `actions/baseline` or `actions/pr-diff` stayed invisible to consumers of the root action, so a release could ship bumped wrapper code while the dispatcher still executed old wrapper code at the pinned SHA. `npm run check:pin-stale` (new `scripts/check-pin-stale.mjs`) fails when the pinned SHA is older than the newest commit touching `actions/`. It runs in `publish.yml` (gated on a published release) rather than on every PR, because the pin is expected to lag wrapper changes on feature branches. The currently-stale pin in `action.yml` (which predated the #136 hosted-baseline fix) has been bumped to the latest `main` commit.
+
+- **Workspace patch releases ship previously-unpublished fixes.** `@snapdrift/compare-core` 1.0.1 and `@snapdrift/adapter-report-md` 1.1.1 publish the #154 and #158 changes that landed after 1.0.0 / 1.1.0 were already on npm; without new versions those fixes would not have shipped. `@snapdrift/manifest` 1.3.0 and `@snapdrift/adapter-fs` 1.1.0 publish for the first time in this release. Workflow examples in the README, Integration Guide, and baseline template now reference `@v0.9.0`.
+
+## 0.8.2 - 2026-08-24
+
+### Fixes
+
+- **Hosted baseline publication is now complete and fail-closed** — a scoped `route-ids` / `--routes` baseline run could publish only the changed routes and replace a larger accepted baseline, causing every omitted route to appear missing on the next PR (i2Dev-com/snap#720). `provider: "snap"` baseline capture now requires every configured route (local baselines, non-publishing captures, and hosted PR diffs remain scopeable), records the exact configured/selected route and viewport set plus one resolved branch/commit and publication workflow identity/sequence, and publishes only when the source run contains a successful stored capture for every expected identity. Complete requests send `publicationMode: "complete"` and `sourceRunId`, reuse the run's `branch` / `prHeadSha` as publication `refBranch` / `refSha`, and derive the baseline id deterministically from the run id so retries are stable. GitHub Actions supplies publication metadata automatically; other CI systems may set the explicit publication metadata variables. Missing, failed, duplicate, unexpected, or stale captures abort without publishing.
+- **Snap outage handling is consistent across the CLI and both wrapper actions** — `warn-and-skip` and `fallback-local` were re-implemented independently in `lib/cli.mjs`, `actions/pr-diff` and `actions/baseline`, and the copies had drifted. `lib/outage-policy.mjs` now holds the single implementation (`captureWithPolicy`, `diffWithPolicy`, `publishBaselineWithPolicy`) that all three call, and the following are fixed as a result (#125):
+  - A `fallback-local` capture in `actions/pr-diff` captured locally but still emitted `provider=snap`, so the compare step rebuilt `SnapProvider` and handed it local results carrying no run id. The steps now receive the *effective* provider.
+  - A `fallback-local` diff swapped only the diff provider. A capture Snap had rendered server-side has a manifest but no PNGs on the runner, so the local pixel engine produced a dimension-only result rather than a comparison. The routes are now recaptured locally first, and the recaptured artifacts are what get staged and uploaded. When no baseline artifact was resolved, the run reports `missing_main_baseline_artifact` instead of crashing the local diff on a missing results file.
+  - `warn-and-skip` exited the wrapper without writing the documented skipped summary, so the PR comment fell through to its "Capture Failed" body. Capture-time and diff-time skips now write a skipped `summary.json`/`summary.md` with reason `snap_unavailable`, expose the summary outputs, stage the report, and exit 0. `diff.mode` is not enforced against a skipped summary.
+  - `actions/baseline` applied no policy at all to `publishBaseline()`. `warn-and-skip` now exits 0 without an artifact, and `fallback-local` captures locally and stages/uploads that bundle, so the run still leaves a usable baseline.
+  - `snapdrift diff` let a capture-time `SnapSkipError` reach the CLI entry point, which exits 1 — the opposite of what `warn-and-skip` is configured to do.
+- **`shouldFailDriftCheck` no longer throws on a skipped summary** — it assumed every summary carried the full diff shape, so the final branch dereferenced `summaryData.errors.length` on `undefined` for the `{ status, reason, message, selectedRoutes }` shape a skipped run writes. `actions/enforce` defaults `summary-path` to exactly where those summaries land, so anyone orchestrating with the low-level actions rather than `actions/pr-diff` got a raw `TypeError` instead of a clean pass whenever a run was skipped for scope, a missing baseline, or a Snap outage. A summary with `status: "skipped"` or no `diff.mode` now returns `false` before any mode branch, and both `shouldFailDriftCheck` and `determineDriftStatus` default their array and counter reads (#132).
+
 ## 0.8.1 - 2026-08-06
 
 ### Fixes

package/README.md

@@ -48,17 +48,19 @@ You keep ownership of checkout, build, startup, readiness, and teardown. SnapDri
 
 ```yaml
 - name: SnapDrift Baseline
-  uses: ranacseruet/snapdrift@v0.8.1
+  uses: ranacseruet/snapdrift@v0.9.0
   with:
     mode: baseline
     repo-config-path: .github/snapdrift.json
 ```
 
+With `provider: "snap"`, baseline publication is a complete, fail-closed snapshot: it must run from the project's default branch and capture every configured route. Snap records the publication workflow identity plus a monotonic sequence so the API can reject stale overlapping publishers. GitHub Actions supplies these values automatically; other CI systems can provide `SNAPDRIFT_PUBLICATION_WORKFLOW_REF` and `SNAPDRIFT_PUBLICATION_SEQUENCE`. Route scoping remains available for pull request diffs, non-publishing `snapdrift capture`, and local-provider baselines.
+
 **3. Run SnapDrift on pull requests:**
 
 ```yaml
 - name: SnapDrift Report
-  uses: ranacseruet/snapdrift@v0.8.1
+  uses: ranacseruet/snapdrift@v0.9.0
   with:
     mode: pr-diff
     github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -69,12 +71,17 @@ That is the full integration. See the [Integration Guide](docs/integration-guide
 
 The root action dispatches on `mode`. The same pipelines are also published as standalone actions — `ranacseruet/snapdrift/actions/baseline` and `ranacseruet/snapdrift/actions/pr-diff` — along with the lower-level `capture`, `compare`, `scope`, `resolve-baseline`, `stage`, `comment`, and `enforce` actions for custom orchestration.
 
+The lower-level `resolve-baseline` action reports `resolution-status` as `found`, `missing`, or
+`error`. A successful lookup with no non-expired artifact is `missing`; GitHub API, permission,
+network, or malformed-response failures are `error` and fail the standalone action so custom
+workflows do not mistake an unavailable baseline for a first-run skip.
+
 ## Local CLI
 
-SnapDrift ships a `snapdrift` CLI for running captures, diffs, migrations, and config initialization locally against a running app — no GitHub Actions required. Use it during development to validate UI changes before pushing.
+SnapDrift ships a `snapdrift` CLI for running captures, diffs, migrations, and config initialization locally against a running app. Use it during development to validate UI changes before pushing. Canonical hosted baseline publication is the exception: `provider: "snap"` baselines require the project default branch plus explicit CI publication metadata; GitHub Actions provides that metadata automatically.
 
 ```bash
-# Establish a baseline — for provider "snap" this also publishes it
+# Establish a local-provider baseline
 snapdrift baseline
 
 # Capture screenshots without publishing anything
@@ -111,6 +118,7 @@ Start with `report-only` while baselines settle. Move to `fail-on-changes` or st
 - One global `diff.threshold`
 - Dimension shifts are reported separately from pixel drift
 - Local provider writes artifacts to the runner filesystem; for a hosted backend with a dashboard and a shared baseline store, configure `provider: "snap"` (see the [Integration Guide](docs/integration-guide.md#hosted-snap-provider))
+- Hosted Snap baselines publish only from the default branch and always include the complete configured route set
 
 ## Outgrew GitHub artifacts?
 

package/action.yml

@@ -15,12 +15,16 @@ branding:
 # action's own directory. `tests/marketplace-metadata.test.js` fails the build if those pins drift
 # from the root `package.json` version.
 #
-# The pins are commit SHAs, so that a consumer pinning this action to a SHA gets an immutable chain
-# rather than a mutable tag one level down. The SHA is the commit holding the wrapper content this
-# release ships — not the release tag itself, which a release commit cannot reference. It therefore
-# only moves when the wrappers change. The trailing comment records the release the pin was last
-# verified for, and the test requires it to match the package version, so every release has to look
-# at it. The test accepts a plain `@vX.Y.Z` tag too, for unreleased refs.
+# Released versions use commit SHAs, so a consumer pinning this action to a SHA gets an immutable
+# chain rather than a mutable tag one level down. Before that release commit exists, an unreleased
+# version uses its upcoming `@vX.Y.Z` tag; the release process replaces it with the commit that holds
+# the wrapper content. The contract test accepts either form and requires the declared version to
+# match package.json.
+#
+# The release workflow also runs `npm run check:pin-stale`, which fails when the pinned SHA predates
+# the newest commit touching `actions/`; that keeps a stale pin from silently serving old wrapper code
+# to Marketplace consumers. The check is release-time only, since the pin is expected to lag wrapper
+# changes on feature branches.
 
 inputs:
   mode:
@@ -32,7 +36,7 @@ inputs:
     required: false
     default: .github/snapdrift.json
   route-ids:
-    description: Optional comma-separated route ids. In `pr-diff` mode, providing these skips changed-file scope detection.
+    description: Optional comma-separated route ids for PR diffs or local baselines. Hosted baselines must capture every configured route.
     required: false
     default: ''
   artifact-retention-days:
@@ -121,6 +125,9 @@ outputs:
   baseline-found:
     description: Whether a usable baseline was found.
     value: ${{ steps.pr-diff.outputs.baseline-found }}
+  baseline-resolution-status:
+    description: 'Baseline lookup status: found, missing, or error.'
+    value: ${{ steps.pr-diff.outputs.baseline-resolution-status }}
   status:
     description: Final SnapDrift status.
     value: ${{ steps.pr-diff.outputs.status }}
@@ -148,7 +155,7 @@ runs:
     - name: SnapDrift baseline
       id: baseline
       if: inputs.mode == 'baseline'
-      uses: ranacseruet/snapdrift/actions/baseline@539953ab07065be805be393d69bd3c9b6d53cf6e # v0.8.1
+      uses: ranacseruet/snapdrift/actions/baseline@331e62a7db4b9e743922667adacfe8fd93e51bb2 # v0.9.0
       with:
         repo-config-path: ${{ inputs.repo-config-path }}
         route-ids: ${{ inputs.route-ids }}
@@ -158,7 +165,7 @@ runs:
     - name: SnapDrift pull request diff
       id: pr-diff
       if: inputs.mode == 'pr-diff'
-      uses: ranacseruet/snapdrift/actions/pr-diff@539953ab07065be805be393d69bd3c9b6d53cf6e # v0.8.1
+      uses: ranacseruet/snapdrift/actions/pr-diff@331e62a7db4b9e743922667adacfe8fd93e51bb2 # v0.9.0
       with:
         github-token: ${{ inputs.github-token }}
         repo-config-path: ${{ inputs.repo-config-path }}

package/actions/baseline/action.yml

@@ -11,7 +11,7 @@ inputs:
     required: false
     default: .github/snapdrift.json
   route-ids:
-    description: Optional comma-separated route ids to capture.
+    description: Optional comma-separated route ids for local-provider baselines. Hosted Snap baselines must capture every configured route.
     required: false
     default: ''
   artifact-retention-days:
@@ -32,16 +32,16 @@ outputs:
     value: ${{ steps.stage.outputs.bundle_dir }}
   results-file:
     description: Absolute path to the generated baseline results file.
-    value: ${{ steps.capture.outputs.results_file }}
+    value: ${{ steps.publish.outputs.results_file || steps.capture.outputs.results_file }}
   manifest-file:
     description: Absolute path to the generated baseline manifest file.
-    value: ${{ steps.capture.outputs.manifest_file }}
+    value: ${{ steps.publish.outputs.manifest_file || steps.capture.outputs.manifest_file }}
   screenshots-root:
     description: Absolute path to the generated screenshots root.
-    value: ${{ steps.capture.outputs.screenshots_root }}
+    value: ${{ steps.publish.outputs.screenshots_root || steps.capture.outputs.screenshots_root }}
   selected-route-ids:
     description: Comma-separated route ids captured in this run.
-    value: ${{ steps.capture.outputs.selected_route_ids }}
+    value: ${{ steps.publish.outputs.selected_route_ids || steps.capture.outputs.selected_route_ids }}
 
 runs:
   using: composite
@@ -103,49 +103,37 @@ runs:
 
         const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
-        const { createProvider, SnapSkipError, SnapFallbackError } = await import(pathToFileURL(providerModulePath));
+        const policyModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/outage-policy.mjs');
+        const { createProvider } = await import(pathToFileURL(providerModulePath));
         const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { captureWithPolicy } = await import(pathToFileURL(policyModulePath));
 
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-        const provider = createProvider(config.provider || 'local', config);
+        const providerName = config.provider || 'local';
 
-        let result;
-        try {
-          result = await provider.capture({
+        const captured = await captureWithPolicy({
+          provider: createProvider(providerName, config),
+          providerName,
+          config,
+          captureOptions: {
             configPath: process.env.REPO_CONFIG_PATH || undefined,
             routeIds: splitCommaList(process.env.ROUTE_IDS),
             purpose: 'baseline'
-          });
-        } catch (err) {
-          if (err instanceof SnapSkipError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable — skipping baseline capture (warn-and-skip).\n`);
-            await fs.appendFile(process.env.GITHUB_OUTPUT, `provider=skipped\n`);
-            process.exit(0);
-          }
-          if (err instanceof SnapFallbackError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable — falling back to local provider.\n`);
-            const { createProvider: cp2 } = await import(pathToFileURL(providerModulePath));
-            result = await cp2('local', config).capture({
-              configPath: process.env.REPO_CONFIG_PATH || undefined,
-              routeIds: splitCommaList(process.env.ROUTE_IDS)
-            });
-            // Report as local so publish is skipped and stage/upload run instead
-            const outputs = [
-              `provider=local`,
-              `results_file=${result.resultsPath}`,
-              `manifest_file=${result.manifestPath}`,
-              `screenshots_root=${result.screenshotsRoot}`,
-              `selected_route_ids=${result.selectedRouteIds.join(',')}`
-            ].join('\n') + '\n';
-            await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
-            process.exit(0);
-          } else {
-            throw err;
-          }
+          },
+          onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable — skipping baseline capture (warn-and-skip).\n'),
+          onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable — falling back to local provider.\n')
+        });
+
+        if (captured.outcome === 'skipped') {
+          await fs.appendFile(process.env.GITHUB_OUTPUT, `provider=skipped\n`);
+          process.exit(0);
         }
 
+        const result = captured.result;
         const outputs = [
-          `provider=${config.provider || 'local'}`,
+          // The effective provider: reporting "local" after a fallback-local
+          // capture is what makes publish skip and stage/upload run instead.
+          `provider=${captured.providerName}`,
           `results_file=${result.resultsPath}`,
           `manifest_file=${result.manifestPath}`,
           `screenshots_root=${result.screenshotsRoot}`,
@@ -160,34 +148,67 @@ runs:
       shell: bash
       env:
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
+        ROUTE_IDS: ${{ inputs.route-ids }}
         RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
       run: |
         node --input-type=module <<'EOF'
+        import fs from 'node:fs/promises';
         import path from 'node:path';
         import { pathToFileURL } from 'node:url';
 
         const providerModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/provider.mjs');
         const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+        const policyModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/outage-policy.mjs');
         const { createProvider } = await import(pathToFileURL(providerModulePath));
-        const { loadSnapdriftConfig } = await import(pathToFileURL(configModulePath));
+        const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { publishBaselineWithPolicy } = await import(pathToFileURL(policyModulePath));
 
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-        const provider = createProvider('snap', config);
 
-        await provider.publishBaseline({
-          resultsPath: process.env.RESULTS_PATH || undefined
+        // Snap can go down after the capture submission succeeds — while polling
+        // the render or posting the baseline. onUnavailable has to cover that
+        // window too, or warn-and-skip still fails the build and fallback-local
+        // still leaves the repo with no baseline artifact. See #125.
+        const published = await publishBaselineWithPolicy({
+          provider: createProvider('snap', config),
+          publishOptions: { resultsPath: process.env.RESULTS_PATH || undefined },
+          captureOptions: {
+            configPath: process.env.REPO_CONFIG_PATH || undefined,
+            routeIds: splitCommaList(process.env.ROUTE_IDS),
+            purpose: 'baseline'
+          },
+          onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable — skipping baseline publish (warn-and-skip).\n'),
+          onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable during publish — capturing locally so the run still produces a baseline artifact.\n')
         });
 
+        if (published.outcome === 'skipped') {
+          await fs.appendFile(process.env.GITHUB_OUTPUT, `provider=skipped\n`);
+          process.exit(0);
+        }
+
+        if (published.outcome === 'fell-back') {
+          const recapture = published.recapture;
+          const outputs = [
+            `provider=local`,
+            `results_file=${recapture.resultsPath}`,
+            `manifest_file=${recapture.manifestPath}`,
+            `screenshots_root=${recapture.screenshotsRoot}`,
+            `selected_route_ids=${recapture.selectedRouteIds.join(',')}`
+          ].join('\n') + '\n';
+          await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
+          process.exit(0);
+        }
+
         process.stdout.write('[SnapDrift] Snap baseline published successfully.\n');
         EOF
 
     - id: stage
-      if: steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
+      if: (steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped') || steps.publish.outputs.provider == 'local'
       shell: bash
       env:
-        RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
-        MANIFEST_PATH: ${{ steps.capture.outputs.manifest_file }}
-        SCREENSHOTS_DIR: ${{ steps.capture.outputs.screenshots_root }}/screenshots
+        RESULTS_PATH: ${{ steps.publish.outputs.results_file || steps.capture.outputs.results_file }}
+        MANIFEST_PATH: ${{ steps.publish.outputs.manifest_file || steps.capture.outputs.manifest_file }}
+        SCREENSHOTS_DIR: ${{ steps.publish.outputs.screenshots_root || steps.capture.outputs.screenshots_root }}/screenshots
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -207,7 +228,7 @@ runs:
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
         EOF
 
-    - if: inputs.upload-artifact == 'true' && steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
+    - if: inputs.upload-artifact == 'true' && ((steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped') || steps.publish.outputs.provider == 'local')
       uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
       with:
         name: ${{ steps.config.outputs.artifact_name }}