snapdrift 0.2.0

package/actions/resolve-baseline/action.yml

@@ -0,0 +1,165 @@
+name: SnapDrift Resolve Baseline
+description: Resolve and download the latest successful SnapDrift baseline from main.
+
+inputs:
+  github-token:
+    description: Token used to query workflow runs and download artifacts.
+    required: true
+  repository:
+    description: Repository in owner/name format.
+    required: false
+    default: ''
+  repo-config-path:
+    description: Path to the SnapDrift config file.
+    required: false
+    default: .github/snapdrift.json
+  artifact-name:
+    description: Optional explicit baseline name override.
+    required: false
+    default: ''
+  workflow-id:
+    description: Workflow id or filename to search.
+    required: false
+    default: ci.yml
+  branch:
+    description: Branch that publishes the baseline.
+    required: false
+    default: main
+  download-path:
+    description: Directory where the artifact should be downloaded.
+    required: false
+    default: snapdrift-baseline-download
+
+outputs:
+  found:
+    description: Whether a non-expired baseline was found.
+    value: ${{ steps.resolve.outputs.found }}
+  artifact-name:
+    description: Resolved artifact name.
+    value: ${{ steps.resolve.outputs.artifact_name }}
+  head-sha:
+    description: Head SHA of the baseline-producing run.
+    value: ${{ steps.resolve.outputs.head_sha }}
+  run-id:
+    description: Workflow run id that produced the baseline.
+    value: ${{ steps.resolve.outputs.run_id }}
+  message:
+    description: Informational message when no artifact was found.
+    value: ${{ steps.resolve.outputs.message }}
+  results-file:
+    description: Path to the downloaded baseline results JSON.
+    value: ${{ steps.paths.outputs.results_file }}
+  manifest-file:
+    description: Path to the downloaded baseline screenshot manifest.
+    value: ${{ steps.paths.outputs.manifest_file }}
+  run-dir:
+    description: Root directory for the downloaded artifact.
+    value: ${{ steps.paths.outputs.run_dir }}
+  screenshots-dir:
+    description: Root directory containing downloaded baseline screenshots.
+    value: ${{ steps.paths.outputs.screenshots_dir }}
+
+runs:
+  using: composite
+  steps:
+    - id: resolve
+      uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+      env:
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
+        INPUT_ARTIFACT_NAME: ${{ inputs.artifact-name }}
+        INPUT_REPOSITORY: ${{ inputs.repository }}
+        INPUT_WORKFLOW_ID: ${{ inputs.workflow-id }}
+        INPUT_BRANCH: ${{ inputs.branch }}
+      with:
+        github-token: ${{ inputs.github-token }}
+        script: |
+          const path = require('path');
+          const { pathToFileURL } = require('url');
+
+          const repository = process.env.INPUT_REPOSITORY || `${context.repo.owner}/${context.repo.repo}`;
+          const [owner, repo] = repository.split('/');
+          const modulePath = path.resolve(process.env.GITHUB_WORKSPACE, process.env.GITHUB_ACTION_PATH, '..', '..', 'lib', 'snapdrift-config.mjs');
+          const { loadSnapdriftConfig } = await import(pathToFileURL(modulePath));
+          const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+          const artifactName = process.env.INPUT_ARTIFACT_NAME || config.baselineArtifactName;
+
+          try {
+            const runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
+              owner,
+              repo,
+              workflow_id: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
+              branch: process.env.INPUT_BRANCH || 'main',
+              event: 'push',
+              per_page: 20
+            });
+
+            let selectedRun = null;
+            let selectedArtifact = null;
+
+            for (const run of runs) {
+              if (run.status !== 'completed' || run.conclusion !== 'success') {
+                continue;
+              }
+
+              const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+                owner,
+                repo,
+                run_id: run.id,
+                per_page: 100
+              });
+
+              const match = artifacts.data.artifacts.find((artifact) => artifact.name === artifactName && !artifact.expired);
+              if (match) {
+                selectedRun = run;
+                selectedArtifact = match;
+                break;
+              }
+            }
+
+            if (!selectedRun || !selectedArtifact) {
+              core.setOutput('found', 'false');
+              core.setOutput('artifact_name', artifactName);
+              core.setOutput('message', `No non-expired SnapDrift baseline artifact named ${artifactName} was found.`);
+              return;
+            }
+
+            core.setOutput('found', 'true');
+            core.setOutput('artifact_name', selectedArtifact.name);
+            core.setOutput('head_sha', selectedRun.head_sha);
+            core.setOutput('run_id', String(selectedRun.id));
+            core.setOutput('message', '');
+          } catch (error) {
+            core.setOutput('found', 'false');
+            core.setOutput('artifact_name', artifactName);
+            core.setOutput('message', `Unable to resolve the SnapDrift baseline artifact: ${error.message}`);
+          }
+
+    - if: steps.resolve.outputs.found == 'true'
+      uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+      with:
+        github-token: ${{ inputs.github-token }}
+        repository: ${{ inputs.repository || github.repository }}
+        run-id: ${{ steps.resolve.outputs.run_id }}
+        name: ${{ steps.resolve.outputs.artifact_name }}
+        path: ${{ inputs.download-path }}
+
+    - id: paths
+      if: steps.resolve.outputs.found == 'true'
+      shell: bash
+      env:
+        DOWNLOAD_PATH: ${{ inputs.download-path }}
+      run: |
+        set -euo pipefail
+        RESULTS_FILE="$(find "$DOWNLOAD_PATH" -type f -name 'results.json' | head -n 1)"
+        MANIFEST_FILE="$(find "$DOWNLOAD_PATH" -type f -name 'manifest.json' | head -n 1)"
+        if [ -z "$RESULTS_FILE" ] || [ -z "$MANIFEST_FILE" ]; then
+          echo "Downloaded artifact did not contain the expected SnapDrift baseline files."
+          find "$DOWNLOAD_PATH" -maxdepth 5 -type f | sort || true
+          exit 1
+        fi
+        {
+          echo "results_file=$RESULTS_FILE"
+          echo "manifest_file=$MANIFEST_FILE"
+          echo "run_dir=${GITHUB_WORKSPACE}/${DOWNLOAD_PATH}"
+          echo "screenshots_dir=$(dirname "$MANIFEST_FILE")/screenshots"
+        } >> "$GITHUB_OUTPUT"

package/actions/scope/action.yml

@@ -0,0 +1,107 @@
+name: SnapDrift Scope
+description: Determine whether SnapDrift should run and which configured routes should be selected for the current change set.
+
+inputs:
+  github-token:
+    description: Token used to query pull request changed files.
+    required: true
+  repo-config-path:
+    description: Path to the SnapDrift config file.
+    required: false
+    default: .github/snapdrift.json
+  pr-number:
+    description: Pull request number for changed-file inspection. When omitted, the action falls back to running all routes.
+    required: false
+    default: ''
+  force-run:
+    description: Whether to force a full SnapDrift run without inspecting changed files.
+    required: false
+    default: 'false'
+  force-run-reason:
+    description: Reason to report when force-run is enabled.
+    required: false
+    default: 'forced'
+
+outputs:
+  should-run:
+    description: Whether SnapDrift should run.
+    value: ${{ steps.scope.outputs.should_run }}
+  reason:
+    description: Reason for the scope decision.
+    value: ${{ steps.scope.outputs.reason }}
+  selected-route-ids:
+    description: Comma-separated route ids selected for the run.
+    value: ${{ steps.scope.outputs.selected_route_ids }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set action root path
+      shell: bash
+      run: echo "ACTION_ROOT=$(cd "$GITHUB_ACTION_PATH/../.." && pwd)" >> "$GITHUB_ENV"
+
+    - id: scope
+      uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+      env:
+        REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
+        INPUT_PR_NUMBER: ${{ inputs.pr-number }}
+        FORCE_RUN: ${{ inputs.force-run }}
+        FORCE_RUN_REASON: ${{ inputs.force-run-reason }}
+      with:
+        github-token: ${{ inputs.github-token }}
+        script: |
+          const path = require('path');
+          const { pathToFileURL } = require('url');
+
+          const configModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+          const { loadSnapdriftConfig, selectRoutesForChangedFiles } = await import(pathToFileURL(configModulePath));
+          const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+
+          const allRouteIds = (config.routes || []).map((route) => route.id);
+          const resolvedPrNumber = Number(process.env.INPUT_PR_NUMBER || context.payload.pull_request?.number || '');
+
+          function setOutputs(scope) {
+            core.setOutput('should_run', scope.shouldRun ? 'true' : 'false');
+            core.setOutput('reason', scope.reason);
+            core.setOutput('selected_route_ids', (scope.selectedRouteIds || []).join(','));
+          }
+
+          if (process.env.FORCE_RUN === 'true') {
+            setOutputs({
+              shouldRun: true,
+              reason: process.env.FORCE_RUN_REASON || 'forced',
+              selectedRouteIds: allRouteIds
+            });
+            return;
+          }
+
+          if (!Number.isFinite(resolvedPrNumber) || resolvedPrNumber <= 0) {
+            setOutputs({
+              shouldRun: true,
+              reason: 'missing_pr_number',
+              selectedRouteIds: allRouteIds
+            });
+            return;
+          }
+
+          try {
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: resolvedPrNumber,
+              per_page: 100
+            });
+
+            const scope = selectRoutesForChangedFiles(
+              config,
+              files.map((file) => file.filename)
+            );
+            setOutputs(scope);
+          } catch (error) {
+            core.warning(`Unable to inspect PR files for SnapDrift scope; running all configured captures instead. ${error.message}`);
+            setOutputs({
+              shouldRun: true,
+              reason: 'snapdrift_scope_check_failed',
+              selectedRouteIds: allRouteIds
+            });
+          }

package/actions/stage/action.yml

@@ -0,0 +1,116 @@
+name: SnapDrift Stage
+description: Stage baseline or drift artifacts into the SnapDrift bundle structure before upload.
+
+inputs:
+  artifact-type:
+    description: Either baseline or diff.
+    required: true
+  bundle-dir:
+    description: Output bundle directory.
+    required: false
+    default: ''
+  results-path:
+    description: Baseline results path for baseline artifact staging.
+    required: false
+    default: ''
+  manifest-path:
+    description: Baseline manifest path for baseline artifact staging.
+    required: false
+    default: ''
+  screenshots-dir:
+    description: Screenshots directory for baseline artifact staging.
+    required: false
+    default: ''
+  summary-json-path:
+    description: Diff summary JSON path.
+    required: false
+    default: ''
+  summary-markdown-path:
+    description: Diff summary markdown path.
+    required: false
+    default: ''
+  baseline-results-path:
+    description: Baseline results path for diff artifact staging.
+    required: false
+    default: ''
+  current-results-path:
+    description: Current results path for diff artifact staging.
+    required: false
+    default: ''
+  baseline-manifest-path:
+    description: Baseline manifest path for diff artifact staging.
+    required: false
+    default: ''
+  current-manifest-path:
+    description: Current manifest path for diff artifact staging.
+    required: false
+    default: ''
+  baseline-screenshots-dir:
+    description: Baseline screenshots dir for diff artifact staging.
+    required: false
+    default: ''
+  current-screenshots-dir:
+    description: Current screenshots dir for diff artifact staging.
+    required: false
+    default: ''
+
+outputs:
+  bundle-dir:
+    description: The staged artifact bundle directory.
+    value: ${{ steps.stage.outputs.bundle_dir }}
+
+runs:
+  using: composite
+  steps:
+    - name: Set action root path
+      shell: bash
+      run: echo "ACTION_ROOT=$(cd "$GITHUB_ACTION_PATH/../.." && pwd)" >> "$GITHUB_ENV"
+
+    - name: Set up Node.js
+      uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      with:
+        node-version: '22'
+
+    - id: stage
+      shell: bash
+      env:
+        ARTIFACT_TYPE: ${{ inputs.artifact-type }}
+        BUNDLE_DIR: ${{ inputs.bundle-dir }}
+        RESULTS_PATH: ${{ inputs.results-path }}
+        MANIFEST_PATH: ${{ inputs.manifest-path }}
+        SCREENSHOTS_DIR: ${{ inputs.screenshots-dir }}
+        SUMMARY_JSON_PATH: ${{ inputs.summary-json-path }}
+        SUMMARY_MARKDOWN_PATH: ${{ inputs.summary-markdown-path }}
+        BASELINE_RESULTS_PATH: ${{ inputs.baseline-results-path }}
+        CURRENT_RESULTS_PATH: ${{ inputs.current-results-path }}
+        BASELINE_MANIFEST_PATH: ${{ inputs.baseline-manifest-path }}
+        CURRENT_MANIFEST_PATH: ${{ inputs.current-manifest-path }}
+        BASELINE_SCREENSHOTS_DIR: ${{ inputs.baseline-screenshots-dir }}
+        CURRENT_SCREENSHOTS_DIR: ${{ inputs.current-screenshots-dir }}
+      run: |
+        node --input-type=module <<'EOF'
+        import fs from 'node:fs/promises';
+        import path from 'node:path';
+        import { pathToFileURL } from 'node:url';
+
+        const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/stage-artifacts.mjs');
+        const { stageArtifacts } = await import(pathToFileURL(modulePath));
+
+        const result = await stageArtifacts({
+          artifactType: process.env.ARTIFACT_TYPE,
+          bundleDir: process.env.BUNDLE_DIR || undefined,
+          resultsPath: process.env.RESULTS_PATH || undefined,
+          manifestPath: process.env.MANIFEST_PATH || undefined,
+          screenshotsDir: process.env.SCREENSHOTS_DIR || undefined,
+          summaryJsonPath: process.env.SUMMARY_JSON_PATH || undefined,
+          summaryMarkdownPath: process.env.SUMMARY_MARKDOWN_PATH || undefined,
+          baselineResultsPath: process.env.BASELINE_RESULTS_PATH || undefined,
+          currentResultsPath: process.env.CURRENT_RESULTS_PATH || undefined,
+          baselineManifestPath: process.env.BASELINE_MANIFEST_PATH || undefined,
+          currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
+          baselineScreenshotsDir: process.env.BASELINE_SCREENSHOTS_DIR || undefined,
+          currentScreenshotsDir: process.env.CURRENT_SCREENSHOTS_DIR || undefined
+        });
+
+        await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
+        EOF

package/bin/snapdrift.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { pathToFileURL } from 'node:url';
+
+// Resolve cli.mjs relative to this file so the bin entry works regardless of
+// where the consumer installs the package.
+const cliPath = new URL('../lib/cli.mjs', import.meta.url).pathname;
+const { main } = await import(pathToFileURL(cliPath).href);
+
+main(process.argv).catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/docs/contracts.md

@@ -0,0 +1,233 @@
+# Contracts
+
+## Config
+
+SnapDrift reads runtime behavior from `.github/snapdrift.json` by default.
+
+### Required fields
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `baselineArtifactName` | `string` | Uploaded baseline artifact name |
+| `workingDirectory` | `string` | Root directory for resolving relative paths |
+| `baseUrl` | `string` | URL where the running app is reachable |
+| `resultsFile` | `string` | Path for capture results JSON |
+| `manifestFile` | `string` | Path for screenshot manifest JSON |
+| `screenshotsRoot` | `string` | Parent directory for screenshot output |
+| `routes` | `array` | Route list to capture |
+| `diff.threshold` | `number` | Max allowed mismatch ratio per screenshot |
+| `diff.mode` | `string` | One of `report-only`, `fail-on-changes`, `fail-on-incomplete`, `strict` |
+
+### Route entry
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `id` | `string` | Unique route identifier across runs |
+| `path` | `string` | URL path appended to `baseUrl` |
+| `viewport` | `string` or `object` | Preset name (`"desktop"`, `"mobile"`) or a custom object `{ "width": number, "height": number }` |
+| `changePaths` | `string[]` | Optional prefixes used for changed-file scoping |
+
+### Optional fields
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `selection.sharedPrefixes` | `string[]` | Prefixes that force the full route set |
+| `selection.sharedExact` | `string[]` | Exact files that force the full route set |
+
+### Example
+
+```json
+{
+  "baselineArtifactName": "ui-foundation-snapdrift-baseline",
+  "workingDirectory": ".",
+  "baseUrl": "http://127.0.0.1:8080",
+  "resultsFile": "qa-artifacts/snapdrift/baseline/current/results.json",
+  "manifestFile": "qa-artifacts/snapdrift/baseline/current/manifest.json",
+  "screenshotsRoot": "qa-artifacts/snapdrift/baseline/current",
+  "routes": [
+    { "id": "root-index-desktop", "path": "/", "viewport": "desktop" },
+    { "id": "root-index-mobile", "path": "/", "viewport": "mobile" }
+  ],
+  "diff": {
+    "threshold": 0.01,
+    "mode": "report-only"
+  }
+}
+```
+
+## Baseline artifact
+
+The published baseline bundle contains:
+
+| File | Description |
+|:-----|:------------|
+| `results.json` | Capture results with per-route status and timing |
+| `manifest.json` | Screenshot manifest with ids, paths, and dimensions |
+| `screenshots/*.png` | Captured screenshot images |
+
+## Drift artifact
+
+The pull request drift bundle contains:
+
+| File | Description |
+|:-----|:------------|
+| `summary.json` | Structured SnapDrift summary |
+| `summary.md` | Human-readable SnapDrift report |
+| `baseline/results.json` | Baseline capture results |
+| `baseline/manifest.json` | Baseline manifest |
+| `baseline/screenshots/*.png` | Baseline images |
+| `current/results.json` | Current capture results |
+| `current/manifest.json` | Current manifest |
+| `current/screenshots/*.png` | Current images |
+
+## Screenshot manifest shape
+
+```json
+{
+  "generatedAt": "2024-01-01T00:00:00.000Z",
+  "baseUrl": "http://127.0.0.1:8080",
+  "screenshots": [
+    {
+      "id": "root-index-desktop",
+      "path": "/",
+      "viewport": "desktop",
+      "imagePath": "screenshots/root-index-desktop.png",
+      "width": 1440,
+      "height": 900
+    }
+  ]
+}
+```
+
+## Summary shape
+
+```json
+{
+  "startedAt": "2024-01-01T00:00:00.000Z",
+  "finishedAt": "2024-01-01T00:00:01.000Z",
+  "completed": true,
+  "status": "clean",
+  "diffMode": "report-only",
+  "threshold": 0.01,
+  "totalScreenshots": 1,
+  "matchedScreenshots": 1,
+  "changedScreenshots": 0,
+  "missingInBaseline": 0,
+  "missingInCurrent": 0,
+  "selectedRoutes": ["root-index-desktop"],
+  "changed": [],
+  "missing": [],
+  "errors": [],
+  "dimensionChanges": [],
+  "baselineResultsPath": "...",
+  "currentResultsPath": "...",
+  "baselineManifestPath": "...",
+  "currentManifestPath": "...",
+  "baselineArtifactName": "ui-foundation-snapdrift-baseline",
+  "baselineSourceSha": "abc1234"
+}
+```
+
+### Status values
+
+| Status | Meaning |
+|:-------|:--------|
+| `clean` | All captures matched within threshold |
+| `changes-detected` | One or more captures exceeded threshold |
+| `incomplete` | Missing captures, dimension shifts, or comparison errors occurred |
+| `skipped` | The report was intentionally skipped |
+
+### Skipped summary
+
+```json
+{
+  "status": "skipped",
+  "reason": "no_snapdrift_relevant_changes",
+  "message": "No drift-relevant changes were detected in this pull request.",
+  "selectedRoutes": []
+}
+```
+
+Additional missing-baseline fields: `baselineAvailable`, `currentResultsPath`.
+
+## Drift semantics
+
+- Screenshots are matched by `id`
+- Mismatch ratio is `different_pixels / total_pixels`
+- `diff.threshold` applies per screenshot
+- Missing captures are counted separately from drift signals
+- Dimension mismatches skip pixel comparison and land in `dimensionChanges[]`
+- `diff.mode` controls enforcement, not summary generation
+
+## Drift modes
+
+| Mode | Stops the run when |
+|:-----|:-------------------|
+| `report-only` | Never |
+| `fail-on-changes` | `changedScreenshots > 0` |
+| `fail-on-incomplete` | Errors, dimension shifts, or missing captures occur |
+| `strict` | Any drift or incomplete comparison appears |
+
+## Viewport presets
+
+| Preset | Width | Height | Scale factor | Mobile | Touch |
+|:-------|------:|-------:|-------------:|:-------|:------|
+| `desktop` | 1440 | 900 | 1 | No | No |
+| `mobile` | 390 | 844 | 3 | Yes | Yes |
+
+## Capture defaults
+
+| Setting | Value |
+|:--------|:------|
+| Navigation wait | `networkidle` |
+| Navigation timeout | 30000ms |
+| Settle delay | 300ms |
+
+## Local CLI directory layout
+
+When using the `snapdrift` CLI, outputs are written to `.snapdrift/` by default:
+
+```
+.snapdrift/
+  baseline/             # written by: snapdrift capture
+    results.json
+    manifest.json
+    screenshots/*.png
+  current/              # written by: snapdrift diff
+    results.json
+    manifest.json
+    screenshots/*.png
+  diff/                 # written by: snapdrift diff
+    summary.json
+    summary.md
+    report.html
+```
+
+All three directories can be overridden with `--baseline-dir`, `--current-dir`, and `--diff-dir`. See the [Local CLI guide](local-cli.md) for details.
+
+## Primary entrypoints
+
+- `actions/baseline`
+- `actions/pr-diff`
+- `snapdrift` CLI (local development)
+
+## Advanced environment variables
+
+These are for custom orchestration only. Wrapper actions set them automatically.
+
+| Variable | Module | Description |
+|:---------|:-------|:------------|
+| `SNAPDRIFT_CONFIG_PATH` | `snapdrift-config.mjs` | Override config path |
+| `SNAPDRIFT_ROUTE_IDS` | `capture-routes.mjs`, `compare-results.mjs` | Comma-separated route ids |
+| `SNAPDRIFT_BASELINE_RESULTS_PATH` | `compare-results.mjs` | Baseline results path |
+| `SNAPDRIFT_BASELINE_MANIFEST_PATH` | `compare-results.mjs` | Baseline manifest path |
+| `SNAPDRIFT_CURRENT_RESULTS_PATH` | `compare-results.mjs` | Current results path |
+| `SNAPDRIFT_CURRENT_MANIFEST_PATH` | `compare-results.mjs` | Current manifest path |
+| `SNAPDRIFT_BASELINE_RUN_DIR` | `compare-results.mjs` | Baseline screenshot root |
+| `SNAPDRIFT_CURRENT_RUN_DIR` | `compare-results.mjs` | Current screenshot root |
+| `SNAPDRIFT_DRIFT_OUT_DIR` | `compare-results.mjs` | Drift report output directory |
+| `SNAPDRIFT_SUMMARY_PATH` | `compare-results.mjs` | Summary JSON path |
+| `SNAPDRIFT_SUMMARY_MARKDOWN_PATH` | `compare-results.mjs` | Summary markdown path |
+| `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 |