snapdrift 0.3.0 → 0.5.0

package/lib/cli.mjs

@@ -4,8 +4,10 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { runBaselineCapture, generateDriftReport, loadSnapdriftConfig } from '@snapdrift/adapter-fs';
+import { loadSnapdriftConfig } from '@snapdrift/adapter-fs';
 import { shouldFailDriftCheck } from '@snapdrift/manifest';
+import { createProvider } from './provider.mjs';
+import { SnapFallbackError, SnapSkipError } from './snap-provider.mjs';
 import { generateHtmlReport } from './report.mjs';
 
 /** @typedef {import('../types/visual-diff-types').VisualDiffSummary} DriftSummary */
@@ -23,13 +25,17 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  *   routes: string[],
  *   baselineDir: string,
  *   currentDir: string,
- *   diffDir: string
+ *   diffDir: string,
+ *   to?: 'snap' | 'local',
+ *   from?: 'snap',
+ *   acceptCrossEngine?: boolean,
+ *   fromSnapAction?: string
  * }} CliOptions
  */
 
 /**
  * Parse CLI arguments from process.argv (or a provided argv array).
- * Supported commands: capture, diff
+ * Supported commands: capture, diff, migrate-baselines, init
  * Supported flags:
  *   --open              Open the HTML report after diff
  *   --config <path>     Path to snapdrift.json (default: .github/snapdrift.json)
@@ -37,6 +43,10 @@ export const LOCAL_DIFF_SUBDIR = 'diff';
  *   --baseline-dir <p>  Override local baseline directory (default: .snapdrift/baseline)
  *   --current-dir <p>   Override local current-capture directory (default: .snapdrift/current)
  *   --diff-dir <p>      Override local diff-output directory (default: .snapdrift/diff)
+ *   --to <snap|local>   Migration target (migrate-baselines command)
+ *   --from <snap>       Migration source (migrate-baselines --to local)
+ *   --accept-cross-engine  Allow importing baselines from a different capture engine
+ *   --from-snap-action <path>  Snap action workflow YAML path (init command)
  *
  * @param {string[]} argv - process.argv
  * @returns {CliOptions}
@@ -52,6 +62,13 @@ export function parseArgs(argv) {
   let baselineDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_BASELINE_SUBDIR);
   let currentDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_CURRENT_SUBDIR);
   let diffDir = path.resolve(LOCAL_SNAPDRIFT_DIR, LOCAL_DIFF_SUBDIR);
+  /** @type {'snap' | 'local' | undefined} */
+  let to;
+  /** @type {'snap' | undefined} */
+  let from;
+  let acceptCrossEngine = false;
+  /** @type {string | undefined} */
+  let fromSnapAction;
 
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
@@ -72,10 +89,24 @@ export function parseArgs(argv) {
       currentDir = path.resolve(args[++i]);
     } else if (arg === '--diff-dir' && i + 1 < args.length) {
       diffDir = path.resolve(args[++i]);
+    } else if (arg === '--to' && i + 1 < args.length) {
+      const toVal = args[++i];
+      if (toVal === 'snap' || toVal === 'local') {
+        to = toVal;
+      }
+    } else if (arg === '--from' && i + 1 < args.length) {
+      const fromVal = args[++i];
+      if (fromVal === 'snap') {
+        from = fromVal;
+      }
+    } else if (arg === '--accept-cross-engine') {
+      acceptCrossEngine = true;
+    } else if (arg === '--from-snap-action' && i + 1 < args.length) {
+      fromSnapAction = args[++i];
     }
   }
 
-  return { command, open, configPath, routes, baselineDir, currentDir, diffDir };
+  return { command, open, configPath, routes, baselineDir, currentDir, diffDir, to, from, acceptCrossEngine, fromSnapAction };
 }
 
 /**
@@ -148,12 +179,30 @@ function openFile(filePath) {
  */
 export async function runCaptureCommand(opts) {
   process.stdout.write(`Capturing baseline to ${opts.baselineDir} ...\n`);
-  const { selectedRouteIds } = await runBaselineCapture({
-    configPath: opts.configPath,
-    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-    outDir: opts.baselineDir
-  });
-  process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+  const { config } = await loadSnapdriftConfig(opts.configPath);
+  const provider = createProvider(config.provider ?? 'local', config);
+  try {
+    const { selectedRouteIds } = await provider.capture({
+      configPath: opts.configPath,
+      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+      outDir: opts.baselineDir,
+      purpose: 'baseline'
+    });
+    process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+  } catch (error) {
+    if (error instanceof SnapFallbackError) {
+      process.stdout.write('Falling back to local provider for capture...\n');
+      const localProvider = createProvider('local');
+      const { selectedRouteIds } = await localProvider.capture({
+        configPath: opts.configPath,
+        routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+        outDir: opts.baselineDir
+      });
+      process.stdout.write(`Captured ${selectedRouteIds.length} route(s) to ${opts.baselineDir}\n`);
+      return;
+    }
+    throw error;
+  }
 }
 
 /**
@@ -166,12 +215,30 @@ export async function runCaptureCommand(opts) {
 export async function runDiffCommand(opts) {
   process.stdout.write(`Capturing current screenshots to ${opts.currentDir} ...\n`);
   const { config } = await loadSnapdriftConfig(opts.configPath);
+  const provider = createProvider(config.provider ?? 'local', config);
 
-  const currentCapture = await runBaselineCapture({
-    configPath: opts.configPath,
-    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-    outDir: opts.currentDir
-  });
+  let currentCapture;
+  let usedLocalFallback = false;
+  try {
+    currentCapture = await provider.capture({
+      configPath: opts.configPath,
+      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+      outDir: opts.currentDir
+    });
+  } catch (error) {
+    if (error instanceof SnapFallbackError) {
+      process.stdout.write('Falling back to local provider for capture...\n');
+      const localProvider = createProvider('local');
+      currentCapture = await localProvider.capture({
+        configPath: opts.configPath,
+        routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+        outDir: opts.currentDir
+      });
+      usedLocalFallback = true;
+    } else {
+      throw error;
+    }
+  }
 
   process.stdout.write('Comparing against baseline ...\n');
 
@@ -183,16 +250,28 @@ export async function runDiffCommand(opts) {
   const markdownPath = path.join(opts.diffDir, 'summary.md');
   const htmlPath = path.join(opts.diffDir, 'report.html');
 
-  const { summary, markdown } = await generateDriftReport({
-    configPath: opts.configPath,
-    routeIds: opts.routes.length > 0 ? opts.routes : undefined,
-    baselineResultsPath,
-    baselineManifestPath,
-    currentResultsPath: currentCapture.resultsPath,
-    currentManifestPath: currentCapture.manifestPath,
-    baselineRunDir: opts.baselineDir,
-    currentRunDir: currentCapture.screenshotsRoot
-  });
+  const diffProvider = usedLocalFallback ? createProvider('local') : provider;
+  let diffResult;
+  try {
+    diffResult = await diffProvider.diff({
+      configPath: opts.configPath,
+      routeIds: opts.routes.length > 0 ? opts.routes : undefined,
+      baselineResultsPath,
+      baselineManifestPath,
+      currentResultsPath: currentCapture.resultsPath,
+      currentManifestPath: currentCapture.manifestPath,
+      baselineRunDir: opts.baselineDir,
+      currentRunDir: currentCapture.screenshotsRoot
+    });
+  } catch (error) {
+    if (error instanceof SnapSkipError) {
+      process.stdout.write('Visual regression skipped (Snap unavailable, warn-and-skip mode).\n');
+      return;
+    }
+    throw error;
+  }
+
+  const { summary, markdown } = diffResult;
 
   const html = await generateHtmlReport(summary, {
     baselineRunDir: opts.baselineDir,
@@ -218,6 +297,58 @@ export async function runDiffCommand(opts) {
   }
 }
 
+/**
+ * Run the `migrate-baselines` command — migrate baselines between local and Snap.
+ *
+ * @param {CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runMigrateBaselinesCommand(opts) {
+  if (!opts.to || (opts.to !== 'snap' && opts.to !== 'local')) {
+    process.stderr.write('Usage: snapdrift migrate-baselines --to <snap|local> [--from snap] [--accept-cross-engine] [--config <path>] [--baseline-dir <dir>]\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (opts.to === 'local' && opts.from !== 'snap') {
+    process.stderr.write('Error: --to local requires --from snap\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (opts.acceptCrossEngine && opts.to !== 'local') {
+    process.stderr.write('Error: --accept-cross-engine is only valid with --to local\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { runMigrateToSnap, runMigrateToLocal } = await import('./migrate-baselines.mjs');
+  const { config } = await loadSnapdriftConfig(opts.configPath);
+
+  if (opts.to === 'snap') {
+    await runMigrateToSnap(config, opts);
+  } else {
+    await runMigrateToLocal(config, opts);
+  }
+}
+
+/**
+ * Run the `init` command — initialize snapdrift config from a Snap action workflow.
+ *
+ * @param {CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runInitCommand(opts) {
+  if (!opts.fromSnapAction) {
+    process.stderr.write('Usage: snapdrift init --from-snap-action <workflow-yaml-path>\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const { runInitFromAction } = await import('./init-from-action.mjs');
+  await runInitFromAction(opts.fromSnapAction);
+}
+
 /**
  * Main CLI entry point — parse args and dispatch to the appropriate command.
  *
@@ -231,9 +362,13 @@ export async function main(argv) {
     await runCaptureCommand(opts);
   } else if (opts.command === 'diff') {
     await runDiffCommand(opts);
+  } else if (opts.command === 'migrate-baselines') {
+    await runMigrateBaselinesCommand(opts);
+  } else if (opts.command === 'init') {
+    await runInitCommand(opts);
   } else {
     process.stderr.write(
-      `Unknown command: ${opts.command}\nUsage: snapdrift <capture|diff> [options]\n`
+      `Unknown command: ${opts.command}\nUsage: snapdrift <capture|diff|migrate-baselines|init> [options]\n`
     );
     process.exitCode = 1;
   }

package/lib/init-from-action.mjs

@@ -0,0 +1,244 @@
+// @ts-check
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+/** @typedef {import('../types/visual-diff-types').InitWarning} InitWarning */
+
+const DEFAULT_OUTPUT_DIR = '.github';
+const DEFAULT_CONFIG_FILENAME = 'snapdrift.json';
+const MIGRATION_NOTES_FILENAME = 'MIGRATION_NOTES.md';
+
+/**
+ * Find the step that uses the Snap visual testing action.
+ *
+ * @param {object} workflow - Parsed YAML workflow
+ * @returns {{ step: object, jobName: string, stepIndex: number } | null}
+ */
+function findSnapActionStep(workflow) {
+  const jobs = workflow.jobs || {};
+  for (const [jobName, job] of Object.entries(jobs)) {
+    const steps = job.steps || [];
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const uses = step.uses || '';
+      if ((uses.includes('snap/github-action') || uses.includes('i2dev-com/snap')) && uses.includes('action')) {
+        return { step, jobName, stepIndex: i };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Map Snap action enforcement mode to snapdrift diff.mode.
+ *
+ * @param {object} inputs
+ * @returns {string}
+ */
+function mapDiffMode(inputs) {
+  const failOnChanges = inputs['fail-on-changes'] || inputs.fail_on_changes;
+  if (failOnChanges === 'true' || failOnChanges === true) {
+    return 'fail-on-changes';
+  }
+  const failOnIncomplete = inputs['fail-on-incomplete'] || inputs.fail_on_incomplete;
+  if (failOnIncomplete === 'true' || failOnIncomplete === true) {
+    return 'fail-on-incomplete';
+  }
+  return 'report-only';
+}
+
+/**
+ * Extract Snap action inputs and translate to snapdrift config fields.
+ *
+ * @param {object} step - The workflow step using the Snap action
+ * @returns {{ config: object, warnings: InitWarning[] }}
+ */
+function translateStepToConfig(step) {
+  /** @type {InitWarning[]} */
+  const warnings = [];
+  const inputs = step.with || {};
+
+  // Diff settings
+  const threshold = parseFloat(inputs.threshold ?? inputs['diff-threshold'] ?? '0.01');
+  const diffMode = mapDiffMode(inputs);
+
+  // Format warning
+  const format = inputs.format;
+  if (format && format !== 'png') {
+    warnings.push({
+      field: 'format',
+      originalValue: format,
+      message: `SnapDrift only supports PNG screenshots. The Snap action's "format: ${format}" setting has no snapdrift equivalent and will be ignored.`,
+      severity: 'warning'
+    });
+  }
+
+  // Baseline tag warning
+  const baselineTag = inputs.baseline_tag || inputs['baseline-tag'];
+  if (baselineTag) {
+    warnings.push({
+      field: 'baseline_tag',
+      originalValue: baselineTag,
+      message: `SnapDrift uses commit-based baselines. The Snap action's "baseline_tag: ${baselineTag}" is a semantic gap that cannot be automatically translated. SnapDrift always uses the latest baseline from the target branch.`,
+      severity: 'warning'
+    });
+  }
+
+  // Snap provider config (if present in inputs)
+  /** @type {object | undefined} */
+  let snap;
+  const snapApiUrl = inputs['snap-api-url'] || inputs.snap_api_url;
+  const snapApiKeyEnv = inputs['snap-api-key-env'] || inputs.snap_api_key_env;
+  const snapProjectId = inputs['snap-project-id'] || inputs.snap_project_id;
+
+  if (snapApiKeyEnv || snapProjectId) {
+    snap = {};
+    if (snapApiUrl) snap.apiUrl = snapApiUrl;
+    if (snapApiKeyEnv) snap.apiKeyEnv = snapApiKeyEnv;
+    if (snapProjectId) snap.projectId = snapProjectId;
+  }
+
+  const config = {
+    baselineArtifactName: 'snapdrift-baseline',
+    workingDirectory: '.',
+    baseUrl: 'http://localhost:3000',
+    resultsFile: 'qa-artifacts/snapdrift/baseline/current/results.json',
+    manifestFile: 'qa-artifacts/snapdrift/baseline/current/manifest.json',
+    screenshotsRoot: 'qa-artifacts/snapdrift/baseline/current',
+    routes: [],
+    diff: {
+      threshold: isNaN(threshold) ? 0.01 : threshold,
+      mode: diffMode
+    }
+  };
+
+  if (snap) {
+    config.provider = 'snap';
+    config.snap = snap;
+  }
+
+  // Note about routes — cannot be auto-translated from action inputs
+  warnings.push({
+    field: 'routes',
+    originalValue: '',
+    message: 'Routes cannot be automatically translated from the Snap action. You must fill in the routes array in snapdrift.json manually, matching the pages you want to test.',
+    severity: 'note'
+  });
+
+  // Note about baseUrl — cannot be auto-translated
+  warnings.push({
+    field: 'baseUrl',
+    originalValue: '',
+    message: 'The baseUrl was set to a placeholder (http://localhost:3000). Update it to match your app URL before running snapdrift.',
+    severity: 'note'
+  });
+
+  return { config, warnings };
+}
+
+/**
+ * Generate MIGRATION_NOTES.md content.
+ *
+ * @param {InitWarning[]} warnings
+ * @param {string} sourceYamlPath
+ * @returns {string}
+ */
+function generateMigrationNotes(warnings, sourceYamlPath) {
+  const lines = [
+    '# Migration Notes',
+    '',
+    `Generated from: \`${sourceYamlPath}\``,
+    '',
+    '## Warnings',
+    ''
+  ];
+
+  const warningsList = warnings.filter((w) => w.severity === 'warning');
+  if (warningsList.length === 0) {
+    lines.push('No warnings.');
+  } else {
+    for (const w of warningsList) {
+      lines.push(`- **${w.field}**: ${w.message}`);
+    }
+  }
+
+  lines.push('');
+  lines.push('## Notes');
+  lines.push('');
+
+  const notesList = warnings.filter((w) => w.severity === 'note');
+  for (const n of notesList) {
+    lines.push(`- **${n.field}**: ${n.message}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Run the init --from-snap-action codemod.
+ *
+ * Reads a Snap action workflow YAML, translates it into snapdrift.json,
+ * and emits MIGRATION_NOTES.md with warnings.
+ *
+ * @param {string} actionYamlPath - Path to the Snap action workflow YAML
+ * @returns {Promise<{ configPath: string, warningsCount: number }>}
+ */
+export async function runInitFromAction(actionYamlPath) {
+  // Read and parse YAML
+  let workflowContent;
+  try {
+    workflowContent = await fs.readFile(actionYamlPath, 'utf-8');
+  } catch {
+    throw new Error(`Cannot read workflow file: ${actionYamlPath}`);
+  }
+
+  const workflow = yaml.load(workflowContent);
+  if (!workflow || typeof workflow !== 'object') {
+    throw new Error(`Invalid workflow YAML: ${actionYamlPath}`);
+  }
+
+  // Find the Snap action step
+  const snapStep = findSnapActionStep(workflow);
+  if (!snapStep) {
+    throw new Error(
+      `No Snap action step found in ${actionYamlPath}. ` +
+      `Looked for steps with "uses" containing "snap" and "action".`
+    );
+  }
+
+  // Translate
+  const { config, warnings } = translateStepToConfig(snapStep.step);
+
+  // Ensure output directory exists
+  const outputDir = DEFAULT_OUTPUT_DIR;
+  await fs.mkdir(outputDir, { recursive: true });
+
+  const configPath = path.join(outputDir, DEFAULT_CONFIG_FILENAME);
+  const notesPath = path.join(outputDir, MIGRATION_NOTES_FILENAME);
+
+  // Idempotency: refuse to overwrite existing snapdrift.json
+  const configExists = await fs.access(configPath).then(() => true, () => false);
+  if (configExists) {
+    throw new Error(
+      `${configPath} already exists. Remove it manually and re-run to regenerate.`
+    );
+  }
+
+  // Write snapdrift.json
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  // Write MIGRATION_NOTES.md
+  const notesContent = generateMigrationNotes(warnings, actionYamlPath);
+  await fs.writeFile(notesPath, notesContent);
+
+  process.stdout.write(`Created ${configPath}\n`);
+  process.stdout.write(`Created ${notesPath}\n`);
+  if (warnings.length > 0) {
+    process.stdout.write(`${warnings.length} warning(s)/note(s) — review ${notesPath}\n`);
+  }
+
+  return { configPath, warningsCount: warnings.length };
+}