snapdrift 0.8.1 → 0.9.0

package/lib/outage-policy.mjs

@@ -0,0 +1,278 @@
+// @ts-check
+
+/**
+ * Shared `snap.onUnavailable` policy for every SnapDrift entry point.
+ *
+ * `warn-and-skip` and `fallback-local` used to be re-implemented independently
+ * in `lib/cli.mjs`, `actions/pr-diff` and `actions/baseline`, and the copies
+ * drifted apart — see ranacseruet/snapdrift#125:
+ *
+ * - a wrapper capture that fell back to local still reported `provider=snap`,
+ *   so the compare step rebuilt `SnapProvider` and handed it local results with
+ *   no run id;
+ * - a diff-time fallback swapped only the diff provider, so `LocalProvider` was
+ *   asked to pixel-compare a remote Snap capture that has a manifest but no
+ *   PNGs on disk;
+ * - `warn-and-skip` exited the wrapper without writing the documented skipped
+ *   summary, so the PR comment claimed "Capture Failed";
+ * - `actions/baseline` did not apply the policy to `publishBaseline()` at all.
+ *
+ * Every caller now routes through these three helpers, so the error-mode matrix
+ * is defined once.
+ */
+
+import { createProvider } from './provider.mjs';
+import { SnapFallbackError, SnapSkipError, isLocalBaseUrl } from './snap-provider.mjs';
+
+/** @typedef {import('../types/visual-diff-types').VisualProvider} VisualProvider */
+/** @typedef {import('../types/visual-diff-types').ProviderCaptureOptions} CaptureOptions */
+/** @typedef {import('../types/visual-diff-types').ProviderCaptureResult} CaptureResult */
+/** @typedef {import('../types/visual-diff-types').ProviderDiffOptions} DiffOptions */
+/** @typedef {import('../types/visual-diff-types').ProviderDiffResult} DiffResult */
+/** @typedef {import('../types/visual-diff-types').ProviderPublishBaselineOptions} PublishBaselineOptions */
+/** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
+
+/** Reason recorded on the skipped summary written under `warn-and-skip`. */
+export const SNAP_UNAVAILABLE_REASON = 'snap_unavailable';
+
+/** Reason recorded when `fallback-local` has no baseline to compare against. */
+export const MISSING_BASELINE_REASON = 'missing_main_baseline_artifact';
+
+/** @returns {void} */
+function noop() {}
+
+/**
+ * @param {unknown} outageError
+ * @param {'capture' | 'diff'} phase
+ * @param {string | undefined} lookupMessage
+ * @returns {Error}
+ */
+function createBaselineLookupFallbackError(outageError, phase, lookupMessage) {
+  const lookupDetail = typeof lookupMessage === 'string' && lookupMessage.trim().length > 0
+    ? ` ${lookupMessage.trim()}`
+    : '';
+  const outageDetail = outageError instanceof Error && outageError.message
+    ? ` Snap fallback reason: ${outageError.message}`
+    : '';
+  return new Error(
+    `Cannot fall back to a local ${phase} because the GitHub baseline lookup failed.${lookupDetail}${outageDetail}`,
+    { cause: outageError }
+  );
+}
+
+/**
+ * Whether the current capture leaves real PNGs on the runner's filesystem.
+ *
+ * `LocalProvider.diff` reads screenshots off disk, so this is the precondition
+ * for handing it a capture. A remote Snap capture writes only run metadata and
+ * a zero-dimension manifest, which would otherwise diff as a dimension change
+ * for every route.
+ *
+ * @param {string} providerName - Effective provider that produced the capture
+ * @param {VisualRegressionConfig} [config]
+ * @returns {boolean}
+ */
+export function hasLocalScreenshots(providerName, config) {
+  if (providerName !== 'snap') {
+    return true;
+  }
+  return isLocalBaseUrl(config?.baseUrl);
+}
+
+/**
+ * Capture under the configured outage policy.
+ *
+ * @param {{
+ *   provider: VisualProvider,
+ *   providerName?: string,
+ *   captureOptions: CaptureOptions,
+ *   config?: VisualRegressionConfig,
+ *   createLocalProvider?: () => VisualProvider,
+ *   onSkip?: (error: SnapSkipError) => void,
+ *   onFallback?: (error: SnapFallbackError) => void,
+ *   baselineResolutionStatus?: string,
+ *   baselineResolutionMessage?: string
+ * }} options
+ * @returns {Promise<{
+ *   outcome: 'captured' | 'skipped',
+ *   providerName: string,
+ *   result?: CaptureResult,
+ *   localScreenshots: boolean
+ * }>}
+ */
+export async function captureWithPolicy(options) {
+  const providerName = options.providerName || 'local';
+  const createLocalProvider = options.createLocalProvider || (() => createProvider('local'));
+  const onSkip = options.onSkip || noop;
+  const onFallback = options.onFallback || noop;
+
+  try {
+    const result = await options.provider.capture(options.captureOptions);
+    return {
+      outcome: 'captured',
+      providerName,
+      result,
+      localScreenshots: hasLocalScreenshots(providerName, options.config)
+    };
+  } catch (error) {
+    if (error instanceof SnapSkipError) {
+      onSkip(error);
+      return { outcome: 'skipped', providerName, localScreenshots: false };
+    }
+    if (error instanceof SnapFallbackError) {
+      onFallback(error);
+      if (options.baselineResolutionStatus === 'error') {
+        throw createBaselineLookupFallbackError(error, 'capture', options.baselineResolutionMessage);
+      }
+      const result = await createLocalProvider().capture(options.captureOptions);
+      // The rest of the pipeline must be told the *effective* provider, not the
+      // configured one — otherwise it rebuilds SnapProvider around local output.
+      return { outcome: 'captured', providerName: 'local', result, localScreenshots: true };
+    }
+    throw error;
+  }
+}
+
+/**
+ * Diff under the configured outage policy.
+ *
+ * `fallback-local` is only a real fallback when the local engine has something
+ * to compare. Two preconditions have to hold, and neither is guaranteed at the
+ * point Snap goes down mid-run:
+ *
+ * 1. A baseline must exist on disk. Without one the local diff throws on a
+ *    missing results file, so we report `baseline-unavailable` and let the
+ *    caller write the documented missing-baseline summary instead.
+ * 2. The current capture must have local screenshots. A remote Snap capture
+ *    does not, so we recapture locally first rather than diffing a manifest of
+ *    zero-dimension placeholders.
+ *
+ * @param {{
+ *   provider: VisualProvider,
+ *   providerName?: string,
+ *   diffOptions: DiffOptions,
+ *   captureOptions?: CaptureOptions,
+ *   localScreenshots?: boolean,
+ *   baselineAvailable?: boolean,
+ *   createLocalProvider?: () => VisualProvider,
+ *   onSkip?: (error: SnapSkipError) => void,
+ *   onFallback?: (error: SnapFallbackError) => void,
+ *   onRecapture?: () => void,
+ *   onBaselineUnavailable?: () => void,
+ *   baselineResolutionStatus?: string,
+ *   baselineResolutionMessage?: string
+ * }} options
+ * @returns {Promise<{
+ *   outcome: 'diffed' | 'skipped' | 'baseline-unavailable',
+ *   providerName: string,
+ *   result?: DiffResult,
+ *   recapture?: CaptureResult
+ * }>}
+ */
+export async function diffWithPolicy(options) {
+  const providerName = options.providerName || 'local';
+  const createLocalProvider = options.createLocalProvider || (() => createProvider('local'));
+  const onSkip = options.onSkip || noop;
+  const onFallback = options.onFallback || noop;
+  const onRecapture = options.onRecapture || noop;
+  const onBaselineUnavailable = options.onBaselineUnavailable || noop;
+
+  try {
+    const result = await options.provider.diff(options.diffOptions);
+    return { outcome: 'diffed', providerName, result };
+  } catch (error) {
+    if (error instanceof SnapSkipError) {
+      onSkip(error);
+      return { outcome: 'skipped', providerName };
+    }
+    if (!(error instanceof SnapFallbackError)) {
+      throw error;
+    }
+
+    onFallback(error);
+
+    const baselineAvailable = options.baselineAvailable !== undefined
+      ? options.baselineAvailable
+      : Boolean(options.diffOptions.baselineResultsPath);
+    if (!baselineAvailable) {
+      onBaselineUnavailable();
+      if (options.baselineResolutionStatus === 'error') {
+        throw createBaselineLookupFallbackError(error, 'diff', options.baselineResolutionMessage);
+      }
+      return { outcome: 'baseline-unavailable', providerName: 'local' };
+    }
+
+    if (options.baselineResolutionStatus === 'error') {
+      throw createBaselineLookupFallbackError(error, 'diff', options.baselineResolutionMessage);
+    }
+
+    const localProvider = createLocalProvider();
+    let diffOptions = options.diffOptions;
+    /** @type {CaptureResult | undefined} */
+    let recapture;
+
+    if (options.localScreenshots === false) {
+      if (!options.captureOptions) {
+        throw new Error(
+          'Cannot fall back to a local diff: the current capture has no screenshots on disk ' +
+          'and no captureOptions were supplied to recapture with.',
+          { cause: error }
+        );
+      }
+      onRecapture();
+      recapture = await localProvider.capture(options.captureOptions);
+      diffOptions = {
+        ...options.diffOptions,
+        currentResultsPath: recapture.resultsPath,
+        currentManifestPath: recapture.manifestPath,
+        currentRunDir: recapture.screenshotsRoot
+      };
+    }
+
+    const result = await localProvider.diff(diffOptions);
+    return { outcome: 'diffed', providerName: 'local', result, recapture };
+  }
+}
+
+/**
+ * Publish a baseline under the configured outage policy.
+ *
+ * Snap can go down *after* the capture submission succeeds — while polling the
+ * render or posting the baseline — and the user's `onUnavailable` choice has to
+ * hold for that window too. `fallback-local` recaptures locally so the caller
+ * still ends up with a baseline bundle it can stage and upload.
+ *
+ * @param {{
+ *   provider: VisualProvider,
+ *   publishOptions: PublishBaselineOptions,
+ *   captureOptions?: CaptureOptions,
+ *   createLocalProvider?: () => VisualProvider,
+ *   onSkip?: (error: SnapSkipError) => void,
+ *   onFallback?: (error: SnapFallbackError) => void
+ * }} options
+ * @returns {Promise<{ outcome: 'published' | 'skipped' | 'fell-back', recapture?: CaptureResult }>}
+ */
+export async function publishBaselineWithPolicy(options) {
+  const createLocalProvider = options.createLocalProvider || (() => createProvider('local'));
+  const onSkip = options.onSkip || noop;
+  const onFallback = options.onFallback || noop;
+
+  try {
+    await options.provider.publishBaseline(options.publishOptions);
+    return { outcome: 'published' };
+  } catch (error) {
+    if (error instanceof SnapSkipError) {
+      onSkip(error);
+      return { outcome: 'skipped' };
+    }
+    if (error instanceof SnapFallbackError) {
+      onFallback(error);
+      if (!options.captureOptions) {
+        return { outcome: 'fell-back' };
+      }
+      const recapture = await createLocalProvider().capture(options.captureOptions);
+      return { outcome: 'fell-back', recapture };
+    }
+    throw error;
+  }
+}

package/lib/provider.mjs

@@ -64,7 +64,7 @@ export class LocalProvider {
    * Build a PR comment body from a diff summary.
    * LocalProvider omits the dashboard link (no dashboard exists).
    *
-   * @param {Record<string, unknown>} summary
+   * @param {import('@snapdrift/manifest').VisualReportSummary} summary
    * @param {import('../types/visual-diff-types').ProviderCommentMeta} [meta]
    * @returns {string}
    */
@@ -73,7 +73,7 @@ export class LocalProvider {
   }
 }
 
-/** @type {Record<string, (config?: VisualRegressionConfig) => VisualProvider>} */
+/** @type {{ local: (config?: VisualRegressionConfig) => LocalProvider, snap: (config: VisualRegressionConfig) => SnapProvider }} */
 const PROVIDER_FACTORIES = {
   local: () => new LocalProvider(),
   snap: (config) => {
@@ -84,6 +84,24 @@ const PROVIDER_FACTORIES = {
   }
 };
 
+/**
+ * @overload
+ * @param {'snap'} providerName
+ * @param {VisualRegressionConfig} config
+ * @returns {SnapProvider}
+ */
+/**
+ * @overload
+ * @param {'local'} providerName
+ * @param {VisualRegressionConfig} [config]
+ * @returns {LocalProvider}
+ */
+/**
+ * @overload
+ * @param {string} providerName
+ * @param {VisualRegressionConfig} [config]
+ * @returns {VisualProvider}
+ */
 /**
  * Create a VisualProvider instance by name.
  *

package/lib/resolve-baseline-artifact.mjs

@@ -0,0 +1,147 @@
+// @ts-check
+
+/**
+ * @typedef {{
+ *   found: boolean,
+ *   resolutionStatus: 'found' | 'missing',
+ *   artifactName: string,
+ *   headSha?: string,
+ *   runId?: string,
+ *   message: string
+ * }} BaselineResolution
+ */
+
+/**
+ * Resolve the most recent successful, non-expired SnapDrift baseline artifact.
+ *
+ * The GitHub API calls are kept here so the standalone resolver and the PR
+ * wrapper share the same response validation and pagination behavior.
+ *
+ * @param {{
+ *   github: {
+ *     paginate: Function,
+ *     rest: { actions: {
+ *       listWorkflowRuns: Function,
+ *       listWorkflowRunArtifacts: Function
+ *     }}
+ *   },
+ *   repository: string,
+ *   workflowId: string,
+ *   branch: string,
+ *   artifactName: string
+ * }} options
+ * @returns {Promise<BaselineResolution>}
+ */
+export async function resolveBaselineArtifact({
+  github,
+  repository,
+  workflowId,
+  branch,
+  artifactName
+}) {
+  const { owner, repo } = parseBaselineRepository(repository);
+  if (typeof artifactName !== 'string' || artifactName.trim().length === 0) {
+    throw new Error('Invalid baseline artifact name. Expected a non-empty name.');
+  }
+
+  // Search the complete successful-run history so an older, still-valid
+  // baseline remains discoverable; 100 keeps that intentional search to the
+  // fewest API pages GitHub allows.
+  const runs = await github.paginate(github.rest.actions.listWorkflowRuns, {
+    owner,
+    repo,
+    workflow_id: workflowId,
+    branch,
+    event: 'push',
+    per_page: 100
+  });
+
+  if (!Array.isArray(runs)) {
+    throw new Error('GitHub returned an invalid workflow run list.');
+  }
+
+  for (const run of runs) {
+    validateWorkflowRun(run);
+
+    // GitHub returns a null conclusion for queued and in-progress runs. They
+    // are valid records and must be ignored before inspecting terminal fields.
+    if (run.status !== 'completed') {
+      continue;
+    }
+    if (typeof run.conclusion !== 'string') {
+      throw new Error(`GitHub returned a malformed completed workflow run record for run ${run.id}.`);
+    }
+    if (run.conclusion !== 'success') {
+      continue;
+    }
+
+    const artifacts = await github.paginate(github.rest.actions.listWorkflowRunArtifacts, {
+      owner,
+      repo,
+      run_id: run.id,
+      per_page: 100
+    });
+    if (!Array.isArray(artifacts)) {
+      throw new Error(`GitHub returned a malformed artifact list for workflow run ${run.id}.`);
+    }
+
+    // Only the artifact SnapDrift depends on needs strict field validation.
+    // Other artifacts in the same run belong to the consumer workflow and may
+    // legitimately have a different shape.
+    const namedArtifacts = artifacts.filter((artifact) => (
+      artifact && typeof artifact === 'object' && artifact.name === artifactName
+    ));
+    for (const artifact of namedArtifacts) {
+      if (typeof artifact.expired !== 'boolean') {
+        throw new Error(`GitHub returned a malformed baseline artifact record for workflow run ${run.id}.`);
+      }
+    }
+
+    const match = namedArtifacts.find((artifact) => !artifact.expired);
+    if (match) {
+      return {
+        found: true,
+        resolutionStatus: 'found',
+        artifactName: match.name,
+        headSha: run.head_sha,
+        runId: String(run.id),
+        message: ''
+      };
+    }
+  }
+
+  return {
+    found: false,
+    resolutionStatus: 'missing',
+    artifactName,
+    message: `No non-expired SnapDrift baseline artifact named ${artifactName} was found.`
+  };
+}
+
+/**
+ * @param {string} repository
+ * @returns {{owner: string, repo: string}}
+ */
+export function parseBaselineRepository(repository) {
+  const value = String(repository || '').trim();
+  const parts = value.split('/');
+  if (parts.length !== 2 || parts.some((part) => part.trim().length === 0)) {
+    throw new Error(`Invalid baseline repository "${value}". Expected owner/name.`);
+  }
+  return { owner: parts[0].trim(), repo: parts[1].trim() };
+}
+
+/**
+ * @param {unknown} run
+ * @returns {asserts run is {id: number, status: string, head_sha: string, conclusion?: unknown}}
+ */
+function validateWorkflowRun(run) {
+  if (!run || typeof run !== 'object') {
+    throw new Error('GitHub returned a malformed workflow run record.');
+  }
+  const record = /** @type {Record<string, unknown>} */ (run);
+  if (typeof record.id !== 'number' || !Number.isInteger(record.id) || record.id <= 0 ||
+      typeof record.status !== 'string' || typeof record.head_sha !== 'string' || record.head_sha.length === 0) {
+    throw new Error('GitHub returned a malformed workflow run record.');
+  }
+}

package/lib/resolve-baseline-paths.mjs

@@ -0,0 +1,40 @@
+// @ts-check
+
+import path from 'node:path';
+
+/**
+ * @typedef {{
+ *   runDir: string,
+ *   resultsFile: string,
+ *   manifestFile: string,
+ *   screenshotsDir: string,
+ * }} BaselinePaths
+ */
+
+/**
+ * @typedef {{
+ *   workspace: string,
+ *   downloadPath?: string,
+ * }} ResolveBaselinePathsParams
+ */
+
+const DEFAULT_DOWNLOAD_PATH = 'snapdrift-baseline-download';
+
+/**
+ * Resolve the baseline download paths for the resolve-baseline composite action.
+ *
+ * `downloadPath` may be absolute (used directly) or relative to the Actions
+ * workspace (prefixed with `workspace`). Returns the run dir plus the results,
+ * manifest, and screenshots paths derived from it.
+ *
+ * @param {ResolveBaselinePathsParams} params
+ * @returns {BaselinePaths}
+ */
+export function resolveBaselinePaths({ workspace, downloadPath }) {
+  const rel = downloadPath || DEFAULT_DOWNLOAD_PATH;
+  const runDir = path.isAbsolute(rel) ? rel : path.join(workspace, rel);
+  const resultsFile = path.join(runDir, 'results.json');
+  const manifestFile = path.join(runDir, 'manifest.json');
+  const screenshotsDir = path.join(path.dirname(manifestFile), 'screenshots');
+  return { runDir, resultsFile, manifestFile, screenshotsDir };
+}