snapdrift 0.8.1 → 0.9.0

package/actions/pr-diff/action.yml

@@ -71,6 +71,9 @@ outputs:
   baseline-found:
     description: Whether a usable baseline was found.
     value: ${{ steps.finalize.outputs.baseline_found }}
+  baseline-resolution-status:
+    description: 'Baseline lookup status: found, missing, or error.'
+    value: ${{ steps.finalize.outputs.baseline_resolution_status }}
   status:
     description: Final SnapDrift status.
     value: ${{ steps.finalize.outputs.status }}
@@ -182,10 +185,33 @@ runs:
               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.`);
+              }
+            }
+            if (files.length >= 3000) {
+              core.warning('GitHub returned the maximum 3000 changed-file records; the list may be truncated, so running all configured captures.');
+              setOutputs({
+                shouldRun: true,
+                reason: 'changed_files_truncated',
+                selectedRouteIds: allRouteIds
+              });
+              return;
+            }
+            const changedFiles = [...new Set(files.flatMap((file) => [
+              file.filename,
+              ...(file.status === 'renamed' && typeof file.previous_filename === 'string' && file.previous_filename
+                ? [file.previous_filename]
+                : [])
+            ]))];
             setOutputs(
               selectRoutesForChangedFiles(
                 config,
-                files.map((file) => file.filename)
+                changedFiles
               )
             );
           } catch (error) {
@@ -212,61 +238,40 @@ runs:
           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.ACTION_ROOT, 'lib/snapdrift-config.mjs');
+          const resolverModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/resolve-baseline-artifact.mjs');
           const { loadSnapdriftConfig } = await import(pathToFileURL(modulePath));
-          const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-          const artifactName = config.baselineArtifactName;
+          const { resolveBaselineArtifact } = await import(pathToFileURL(resolverModulePath));
+          let artifactName = '';
+
+          const setLookupError = (error) => {
+            const detail = error instanceof Error ? error.message : String(error);
+            const message = `Unable to resolve the SnapDrift baseline artifact: ${detail}`;
+            core.setOutput('found', 'false');
+            core.setOutput('resolution_status', 'error');
+            core.setOutput('artifact_name', artifactName);
+            core.setOutput('message', message);
+            core.warning(message);
+          };
 
           try {
-            const runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
-              owner,
-              repo,
-              workflow_id: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            artifactName = config.baselineArtifactName;
+            const result = await resolveBaselineArtifact({
+              github,
+              repository,
+              workflowId: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
               branch: process.env.INPUT_BRANCH || 'main',
-              event: 'push',
-              per_page: 20
+              artifactName
             });
-
-            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', '');
+            core.setOutput('found', String(result.found));
+            core.setOutput('resolution_status', result.resolutionStatus);
+            core.setOutput('artifact_name', result.artifactName);
+            core.setOutput('head_sha', result.headSha || '');
+            core.setOutput('run_id', result.runId || '');
+            core.setOutput('message', result.message);
           } catch (error) {
-            core.setOutput('found', 'false');
-            core.setOutput('artifact_name', artifactName);
-            core.setOutput('message', `Unable to resolve the SnapDrift baseline artifact: ${error.message}`);
+            setLookupError(error);
           }
 
     - if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found == 'true'
@@ -320,6 +325,16 @@ runs:
         await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
         EOF
 
+    - id: baseline_resolution_guard
+      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.resolution_status == 'error' && steps.config.outputs.provider != 'snap'
+      shell: bash
+      env:
+        BASELINE_MESSAGE: ${{ steps.baseline.outputs.message }}
+      run: |
+        set -euo pipefail
+        printf 'SnapDrift baseline lookup failed. %s\n' "$BASELINE_MESSAGE" >&2
+        exit 1
+
     - name: Install Playwright Chromium
       if: steps.scope.outputs.should_run == 'true' && (steps.config.outputs.provider != 'snap' || steps.config.outputs.on_unavailable == 'fallback-local' || steps.config.outputs.snap_local_capture == 'true')
       shell: bash
@@ -332,6 +347,8 @@ runs:
       env:
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         ROUTE_IDS: ${{ steps.scope.outputs.selected_route_ids }}
+        BASELINE_RESOLUTION_STATUS: ${{ steps.baseline.outputs.resolution_status }}
+        BASELINE_RESOLUTION_MESSAGE: ${{ steps.baseline.outputs.message }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -340,38 +357,56 @@ 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 summaryModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/drift-summary.mjs');
+        const { createProvider } = await import(pathToFileURL(providerModulePath));
         const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { captureWithPolicy, SNAP_UNAVAILABLE_REASON } = await import(pathToFileURL(policyModulePath));
+        const { writeDriftSummary } = await import(pathToFileURL(summaryModulePath));
 
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-        const provider = createProvider(config.provider || 'local', config);
-
-        let result;
-        try {
-          result = await provider.capture({
+        const providerName = config.provider || 'local';
+        const routeIds = splitCommaList(process.env.ROUTE_IDS);
+
+        const captured = await captureWithPolicy({
+          provider: createProvider(providerName, config),
+          providerName,
+          config,
+          captureOptions: {
             configPath: process.env.REPO_CONFIG_PATH || undefined,
-            routeIds: splitCommaList(process.env.ROUTE_IDS)
+            routeIds
+          },
+          baselineResolutionStatus: process.env.BASELINE_RESOLUTION_STATUS,
+          baselineResolutionMessage: process.env.BASELINE_RESOLUTION_MESSAGE,
+          onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable — skipping visual regression (warn-and-skip).\n'),
+          onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable — falling back to local provider.\n')
+        });
+
+        if (captured.outcome === 'skipped') {
+          // warn-and-skip is documented as "write a skipped summary and exit 0".
+          // Without the summary the report step falls through to its
+          // "Capture Failed" body, which is not what happened. See #125.
+          const skipped = await writeDriftSummary({
+            reason: SNAP_UNAVAILABLE_REASON,
+            selectedRouteIds: routeIds
           });
-        } catch (err) {
-          if (err instanceof SnapSkipError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable — skipping visual regression (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)
-            });
-          } else {
-            throw err;
-          }
+          const skipOutputs = [
+            `provider=skipped`,
+            `summary_path=${skipped.summaryPath}`,
+            `markdown_path=${skipped.markdownPath}`,
+            `status=${skipped.summary.status || ''}`
+          ].join('\n') + '\n';
+          await fs.appendFile(process.env.GITHUB_OUTPUT, skipOutputs);
+          process.exit(0);
         }
 
+        const result = captured.result;
         const outputs = [
-          `provider=${config.provider || 'local'}`,
+          // The *effective* provider, not the configured one: after a
+          // fallback-local capture the compare step must not rebuild
+          // SnapProvider around local results that carry no run id.
+          `provider=${captured.providerName}`,
+          `local_screenshots=${captured.localScreenshots ? 'true' : 'false'}`,
           `results_file=${result.resultsPath}`,
           `manifest_file=${result.manifestPath}`,
           `screenshots_root=${result.screenshotsRoot}`,
@@ -394,6 +429,12 @@ runs:
         BASELINE_SOURCE_SHA: ${{ steps.baseline.outputs.head_sha }}
         CURRENT_RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
         CURRENT_MANIFEST_PATH: ${{ steps.capture.outputs.manifest_file }}
+        CURRENT_SCREENSHOTS_ROOT: ${{ steps.capture.outputs.screenshots_root }}
+        CAPTURE_PROVIDER: ${{ steps.capture.outputs.provider }}
+        LOCAL_SCREENSHOTS: ${{ steps.capture.outputs.local_screenshots }}
+        BASELINE_FOUND: ${{ steps.baseline.outputs.found }}
+        BASELINE_RESOLUTION_STATUS: ${{ steps.baseline.outputs.resolution_status }}
+        BASELINE_RESOLUTION_MESSAGE: ${{ steps.baseline.outputs.message }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -402,45 +443,83 @@ 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 summaryModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/drift-summary.mjs');
+        const { createProvider } = await import(pathToFileURL(providerModulePath));
         const { loadSnapdriftConfig, splitCommaList } = await import(pathToFileURL(configModulePath));
+        const { diffWithPolicy, MISSING_BASELINE_REASON, SNAP_UNAVAILABLE_REASON } = await import(pathToFileURL(policyModulePath));
+        const { writeDriftSummary } = await import(pathToFileURL(summaryModulePath));
 
         const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
-        const provider = createProvider(config.provider || 'local', config);
+        // The capture step reports the provider that actually ran, which is
+        // "local" once a fallback-local capture has happened.
+        const providerName = process.env.CAPTURE_PROVIDER || config.provider || 'local';
+        const routeIds = splitCommaList(process.env.ROUTE_IDS);
 
         const resolvedOutDir = path.resolve('qa-artifacts/snapdrift/drift/current');
         const resolvedSummaryPath = path.join(resolvedOutDir, 'summary.json');
         const resolvedMarkdownPath = path.join(resolvedOutDir, 'summary.md');
 
+        const captureOptions = {
+          configPath: process.env.REPO_CONFIG_PATH || undefined,
+          routeIds
+        };
+
         const diffOptions = {
           configPath: process.env.REPO_CONFIG_PATH || undefined,
           baselineResultsPath: process.env.BASELINE_RESULTS_PATH || undefined,
           baselineManifestPath: process.env.BASELINE_MANIFEST_PATH || undefined,
           baselineRunDir: process.env.BASELINE_RUN_DIR || undefined,
-          routeIds: splitCommaList(process.env.ROUTE_IDS),
+          routeIds,
           baselineArtifactName: process.env.BASELINE_ARTIFACT_NAME || undefined,
           baselineSourceSha: process.env.BASELINE_SOURCE_SHA || undefined,
           currentResultsPath: process.env.CURRENT_RESULTS_PATH || undefined,
-          currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined
+          currentManifestPath: process.env.CURRENT_MANIFEST_PATH || undefined,
+          currentRunDir: process.env.CURRENT_SCREENSHOTS_ROOT || undefined
         };
 
-        let diffResult;
-        try {
-          diffResult = await provider.diff(diffOptions);
-        } catch (err) {
-          if (err instanceof SnapSkipError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable during diff — skipping (warn-and-skip).\n`);
-            process.exit(0);
-          }
-          if (err instanceof SnapFallbackError) {
-            process.stderr.write(`[SnapDrift] Snap unavailable during diff — falling back to local provider.\n`);
-            const { createProvider: cp2 } = await import(pathToFileURL(providerModulePath));
-            diffResult = await cp2('local', config).diff(diffOptions);
-          } else {
-            throw err;
+        const diffed = await diffWithPolicy({
+          provider: createProvider(providerName, config),
+          providerName,
+          diffOptions,
+          captureOptions,
+          localScreenshots: process.env.LOCAL_SCREENSHOTS !== 'false',
+          baselineAvailable: process.env.BASELINE_FOUND === 'true',
+          baselineResolutionStatus: process.env.BASELINE_RESOLUTION_STATUS,
+          baselineResolutionMessage: process.env.BASELINE_RESOLUTION_MESSAGE,
+          onSkip: () => process.stderr.write('[SnapDrift] Snap unavailable during diff — skipping (warn-and-skip).\n'),
+          onFallback: () => process.stderr.write('[SnapDrift] Snap unavailable during diff — falling back to local provider.\n'),
+          onRecapture: () => process.stderr.write('[SnapDrift] The current capture was rendered by Snap, so it has no local screenshots — recapturing locally before diffing.\n'),
+          onBaselineUnavailable: () => {
+            if (process.env.BASELINE_RESOLUTION_STATUS === 'error') {
+              process.stderr.write(`[SnapDrift] ${process.env.BASELINE_RESOLUTION_MESSAGE || 'The GitHub baseline lookup failed before local diff fallback.'}\n`);
+              return;
+            }
+            process.stderr.write('[SnapDrift] No baseline artifact is available, so the local diff cannot run.\n');
           }
+        });
+
+        // Every non-throwing outcome writes a summary. A wrapper run that ends
+        // without one makes the report step claim "Capture Failed". See #125.
+        if (diffed.outcome !== 'diffed') {
+          const skipped = await writeDriftSummary({
+            reason: diffed.outcome === 'skipped' ? SNAP_UNAVAILABLE_REASON : MISSING_BASELINE_REASON,
+            baselineAvailable: diffed.outcome === 'skipped' ? undefined : false,
+            currentResultsPath: process.env.CURRENT_RESULTS_PATH || undefined,
+            selectedRouteIds: routeIds,
+            outDir: resolvedOutDir
+          });
+          const skipOutputs = [
+            `skipped=true`,
+            `summary_path=${skipped.summaryPath}`,
+            `markdown_path=${skipped.markdownPath}`,
+            `status=${skipped.summary.status || ''}`
+          ].join('\n') + '\n';
+          await fs.appendFile(process.env.GITHUB_OUTPUT, skipOutputs);
+          process.exit(0);
         }
-        const { summary, markdown } = diffResult;
+
+        const { summary, markdown } = diffed.result;
 
         await fs.mkdir(resolvedOutDir, { recursive: true });
         await Promise.all([
@@ -449,9 +528,16 @@ runs:
         ]);
 
         const outputs = [
+          `skipped=false`,
           `summary_path=${resolvedSummaryPath}`,
           `markdown_path=${resolvedMarkdownPath}`,
-          `status=${summary.status || ''}`
+          `status=${summary.status || ''}`,
+          // A fallback-local diff of a remote Snap capture recaptures on the
+          // runner; the staged bundle has to carry those PNGs, not the empty
+          // placeholder paths the Snap capture step emitted.
+          `current_results_file=${diffed.recapture?.resultsPath || ''}`,
+          `current_manifest_file=${diffed.recapture?.manifestPath || ''}`,
+          `current_screenshots_root=${diffed.recapture?.screenshotsRoot || ''}`
         ].join('\n') + '\n';
 
         await fs.appendFile(process.env.GITHUB_OUTPUT, outputs);
@@ -486,7 +572,7 @@ runs:
         EOF
 
     - id: skipped_baseline
-      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.found != 'true' && steps.capture.outputs.provider != 'snap'
+      if: steps.scope.outputs.should_run == 'true' && steps.baseline.outputs.resolution_status == 'missing' && steps.capture.outputs.provider != 'snap' && steps.capture.outputs.provider != 'skipped'
       shell: bash
       env:
         MESSAGE: ${{ steps.baseline.outputs.message }}
@@ -521,14 +607,14 @@ runs:
     - id: stage
       shell: bash
       env:
-        SUMMARY_JSON_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
-        SUMMARY_MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path }}
+        SUMMARY_JSON_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
+        SUMMARY_MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.capture.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path }}
         BASELINE_RESULTS_PATH: ${{ steps.baseline_paths.outputs.results_file }}
-        CURRENT_RESULTS_PATH: ${{ steps.capture.outputs.results_file }}
+        CURRENT_RESULTS_PATH: ${{ steps.compare.outputs.current_results_file || steps.capture.outputs.results_file }}
         BASELINE_MANIFEST_PATH: ${{ steps.baseline_paths.outputs.manifest_file }}
-        CURRENT_MANIFEST_PATH: ${{ steps.capture.outputs.manifest_file }}
+        CURRENT_MANIFEST_PATH: ${{ steps.compare.outputs.current_manifest_file || steps.capture.outputs.manifest_file }}
         BASELINE_SCREENSHOTS_DIR: ${{ steps.baseline_paths.outputs.screenshots_dir }}
-        CURRENT_SCREENSHOTS_DIR: ${{ steps.capture.outputs.screenshots_root != '' && format('{0}/screenshots', steps.capture.outputs.screenshots_root) || '' }}
+        CURRENT_SCREENSHOTS_ROOT: ${{ steps.compare.outputs.current_screenshots_root || steps.capture.outputs.screenshots_root }}
       run: |
         node --input-type=module <<'EOF'
         import fs from 'node:fs/promises';
@@ -538,6 +624,8 @@ runs:
         const modulePath = path.resolve(process.env.ACTION_ROOT, 'lib/stage-artifacts.mjs');
         const { stageArtifacts } = await import(pathToFileURL(modulePath));
 
+        const currentScreenshotsRoot = process.env.CURRENT_SCREENSHOTS_ROOT || '';
+
         const result = await stageArtifacts({
           artifactType: 'diff',
           summaryJsonPath: process.env.SUMMARY_JSON_PATH || undefined,
@@ -547,7 +635,7 @@ runs:
           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
+          currentScreenshotsDir: currentScreenshotsRoot ? path.join(currentScreenshotsRoot, 'screenshots') : undefined
         });
 
         await fs.appendFile(process.env.GITHUB_OUTPUT, `bundle_dir=${result.bundleDir}\n`);
@@ -563,7 +651,7 @@ runs:
     - if: always()
       shell: bash
       env:
-        SUMMARY_FILE: ${{ steps.compare.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path }}
+        SUMMARY_FILE: ${{ steps.compare.outputs.markdown_path || steps.capture.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path }}
       run: |
         if [ -f "$SUMMARY_FILE" ]; then
           cat "$SUMMARY_FILE" >> "$GITHUB_STEP_SUMMARY"
@@ -573,12 +661,14 @@ runs:
       uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
       env:
         PR_NUMBER: ${{ steps.context.outputs.pr_number }}
-        SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
+        SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path }}
         ARTIFACT_NAME: ${{ steps.context.outputs.artifact_name }}
         RUN_URL: ${{ steps.context.outputs.run_url }}
         REPO_CONFIG_PATH: ${{ inputs.repo-config-path }}
         MAX_CHANGED_ROWS: ${{ inputs.max-changed-rows }}
         MAX_ERROR_ROWS: ${{ inputs.max-error-rows }}
+        BASELINE_RESOLUTION_STATUS: ${{ steps.baseline.outputs.resolution_status }}
+        BASELINE_RESOLUTION_MESSAGE: ${{ steps.baseline.outputs.message }}
       with:
         github-token: ${{ inputs.github-token }}
         script: |
@@ -590,6 +680,8 @@ runs:
           const PR_COMMENT_MARKERS = [PR_COMMENT_MARKER];
           const iconUrl = 'https://raw.githubusercontent.com/ranacseruet/snapdrift/main/assets/snapdrift-logo-icon.png';
           const repoUrl = 'https://github.com/ranacseruet/snapdrift';
+          const prCommentModulePath = path.resolve(process.env.ACTION_ROOT, 'lib/pr-comment.mjs');
+          const { escapeMarkdown } = await import(pathToFileURL(prCommentModulePath));
 
           const summaryPath = process.env.SUMMARY_PATH;
           const issueNumber = Number(process.env.PR_NUMBER || context.payload.pull_request?.number || context.issue?.number || '');
@@ -600,7 +692,12 @@ runs:
 
           if (!summaryPath || !fs.existsSync(summaryPath)) {
             const runUrl = process.env.RUN_URL || '';
-            const body = `${PR_COMMENT_MARKER}\n<img src="${iconUrl}" alt="SnapDrift" width="20" height="20" />\n\n### ⚠️ SnapDrift Report — Capture Failed\n\nSnapDrift did not produce a summary. This usually means capture failed before the report could be assembled.\n\n[View run](${runUrl}) for details.\n\n<div align="right"><sub>Powered by <a href="${repoUrl}">SnapDrift</a></sub></div>`;
+            const lookupFailure = process.env.BASELINE_RESOLUTION_STATUS === 'error';
+            const heading = lookupFailure ? 'Baseline Lookup Failed' : 'Capture Failed';
+            const detail = escapeMarkdown(lookupFailure
+              ? process.env.BASELINE_RESOLUTION_MESSAGE || 'The GitHub baseline lookup failed before comparison could run.'
+              : 'SnapDrift did not produce a summary. This usually means capture failed before the report could be assembled.');
+            const body = `${PR_COMMENT_MARKER}\n<img src="${iconUrl}" alt="SnapDrift" width="20" height="20" />\n\n### ⚠️ SnapDrift Report — ${heading}\n\n${detail}\n\n[View run](${runUrl}) for details.\n\n<div align="right"><sub>Powered by <a href="${repoUrl}">SnapDrift</a></sub></div>`;
             await github.rest.issues.createComment({
               owner: context.repo.owner,
               repo: context.repo.repo,
@@ -674,7 +771,9 @@ runs:
             });
           }
 
-    - if: steps.scope.outputs.should_run == 'true' && steps.capture.outputs.provider != 'skipped' && (steps.baseline.outputs.found == 'true' || steps.capture.outputs.provider == 'snap')
+    # A skipped compare writes a summary with no diff counters, so enforcement
+    # has nothing to evaluate — `warn-and-skip` means "do not fail my build".
+    - if: steps.scope.outputs.should_run == 'true' && steps.capture.outputs.provider != 'skipped' && steps.compare.outputs.skipped != 'true' && (steps.baseline.outputs.found == 'true' || steps.capture.outputs.provider == 'snap')
       shell: bash
       run: |
         node --input-type=module <<'EOF'
@@ -700,9 +799,10 @@ runs:
         SCOPE_REASON: ${{ steps.scope.outputs.reason }}
         SELECTED_ROUTE_IDS: ${{ steps.scope.outputs.selected_route_ids }}
         BASELINE_FOUND: ${{ steps.baseline.outputs.found || 'false' }}
-        STATUS: ${{ steps.compare.outputs.status || steps.skipped_baseline.outputs.status || steps.skipped_scope.outputs.status || '' }}
-        SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path || '' }}
-        MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path || '' }}
+        BASELINE_RESOLUTION_STATUS: ${{ steps.baseline.outputs.resolution_status || '' }}
+        STATUS: ${{ steps.compare.outputs.status || steps.capture.outputs.status || steps.skipped_baseline.outputs.status || steps.skipped_scope.outputs.status || '' }}
+        SUMMARY_PATH: ${{ steps.compare.outputs.summary_path || steps.capture.outputs.summary_path || steps.skipped_baseline.outputs.summary_path || steps.skipped_scope.outputs.summary_path || '' }}
+        MARKDOWN_PATH: ${{ steps.compare.outputs.markdown_path || steps.capture.outputs.markdown_path || steps.skipped_baseline.outputs.markdown_path || steps.skipped_scope.outputs.markdown_path || '' }}
         BUNDLE_DIR: ${{ steps.stage.outputs.bundle_dir }}
       run: |
         {
@@ -710,6 +810,7 @@ runs:
           echo "scope_reason=${SCOPE_REASON:-}"
           echo "selected_route_ids=${SELECTED_ROUTE_IDS:-}"
           echo "baseline_found=${BASELINE_FOUND:-false}"
+          echo "baseline_resolution_status=${BASELINE_RESOLUTION_STATUS:-}"
           echo "status=${STATUS:-}"
           echo "summary_path=${SUMMARY_PATH:-}"
           echo "markdown_path=${MARKDOWN_PATH:-}"

package/actions/resolve-baseline/action.yml

@@ -38,6 +38,9 @@ outputs:
   found:
     description: Whether a non-expired baseline was found.
     value: ${{ steps.resolve.outputs.found }}
+  resolution-status:
+    description: 'Baseline lookup status: found, missing, or error.'
+    value: ${{ steps.resolve.outputs.resolution_status }}
   artifact-name:
     description: Resolved artifact name.
     value: ${{ steps.resolve.outputs.artifact_name }}
@@ -48,7 +51,7 @@ outputs:
     description: Workflow run id that produced the baseline.
     value: ${{ steps.resolve.outputs.run_id }}
   message:
-    description: Informational message when no artifact was found.
+    description: Resolution message for a missing or failed lookup.
     value: ${{ steps.resolve.outputs.message }}
   results-file:
     description: Path to the downloaded baseline results JSON.
@@ -81,61 +84,40 @@ runs:
           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 resolverModulePath = path.resolve(process.env.GITHUB_WORKSPACE, process.env.GITHUB_ACTION_PATH, '..', '..', 'lib', 'resolve-baseline-artifact.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;
+          const { resolveBaselineArtifact } = await import(pathToFileURL(resolverModulePath));
+          let artifactName = process.env.INPUT_ARTIFACT_NAME || '';
+
+          const setLookupError = (error) => {
+            const detail = error instanceof Error ? error.message : String(error);
+            const message = `Unable to resolve the SnapDrift baseline artifact: ${detail}`;
+            core.setOutput('found', 'false');
+            core.setOutput('resolution_status', 'error');
+            core.setOutput('artifact_name', artifactName);
+            core.setOutput('message', message);
+            core.setFailed(message);
+          };
 
           try {
-            const runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
-              owner,
-              repo,
-              workflow_id: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
+            const { config } = await loadSnapdriftConfig(process.env.REPO_CONFIG_PATH || undefined);
+            artifactName = process.env.INPUT_ARTIFACT_NAME || config.baselineArtifactName;
+            const result = await resolveBaselineArtifact({
+              github,
+              repository,
+              workflowId: process.env.INPUT_WORKFLOW_ID || 'ci.yml',
               branch: process.env.INPUT_BRANCH || 'main',
-              event: 'push',
-              per_page: 20
+              artifactName
             });
-
-            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', '');
+            core.setOutput('found', String(result.found));
+            core.setOutput('resolution_status', result.resolutionStatus);
+            core.setOutput('artifact_name', result.artifactName);
+            core.setOutput('head_sha', result.headSha || '');
+            core.setOutput('run_id', result.runId || '');
+            core.setOutput('message', result.message);
           } catch (error) {
-            core.setOutput('found', 'false');
-            core.setOutput('artifact_name', artifactName);
-            core.setOutput('message', `Unable to resolve the SnapDrift baseline artifact: ${error.message}`);
+            setLookupError(error);
           }
 
     - if: steps.resolve.outputs.found == 'true'
@@ -164,6 +146,10 @@ runs:
         {
           echo "results_file=$RESULTS_FILE"
           echo "manifest_file=$MANIFEST_FILE"
-          echo "run_dir=${GITHUB_WORKSPACE}/${DOWNLOAD_PATH}"
+          case "$DOWNLOAD_PATH" in
+            /*) RUN_DIR="$DOWNLOAD_PATH" ;;
+            *) RUN_DIR="${GITHUB_WORKSPACE}/${DOWNLOAD_PATH}" ;;
+          esac
+          echo "run_dir=$RUN_DIR"
           echo "screenshots_dir=$(dirname "$MANIFEST_FILE")/screenshots"
         } >> "$GITHUB_OUTPUT"