snapdrift 0.3.0 → 0.4.0

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 };
+}

package/lib/migrate-baselines.mjs

@@ -0,0 +1,199 @@
+// @ts-check
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { createProvider } from './provider.mjs';
+
+/**
+ * Resolve the current commit HEAD SHA.
+ * Tries GITHUB_SHA first, then git rev-parse HEAD.
+ * @returns {string}
+ */
+function resolveHeadSha() {
+  if (process.env.GITHUB_SHA) {
+    return process.env.GITHUB_SHA;
+  }
+  try {
+    return execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim();
+  } catch {
+    throw new Error(
+      'Cannot resolve commit SHA. Set GITHUB_SHA or run inside a git repository.'
+    );
+  }
+}
+
+/**
+ * Read local baseline files from a directory.
+ *
+ * @param {string} baselineDir
+ * @returns {Promise<{ results: object, manifest: object, screenshots: Array<{ filename: string, data: string }>, headSha: string }>}
+ */
+export async function readLocalBaselines(baselineDir) {
+  const resultsPath = path.join(baselineDir, 'results.json');
+  const manifestPath = path.join(baselineDir, 'manifest.json');
+  const screenshotsDir = path.join(baselineDir, 'screenshots');
+
+  let results;
+  try {
+    results = JSON.parse(await fs.readFile(resultsPath, 'utf-8'));
+  } catch {
+    throw new Error(`Cannot read baseline results: ${resultsPath}`);
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+  } catch {
+    throw new Error(`Cannot read baseline manifest: ${manifestPath}`);
+  }
+
+  const screenshots = [];
+  try {
+    const entries = await fs.readdir(screenshotsDir);
+    for (const entry of entries) {
+      if (!entry.endsWith('.png')) continue;
+      const filePath = path.join(screenshotsDir, entry);
+      const buffer = await fs.readFile(filePath);
+      screenshots.push({
+        filename: entry,
+        data: buffer.toString('base64')
+      });
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  const headSha = results.headSha || resolveHeadSha();
+
+  return { results, manifest, screenshots, headSha };
+}
+
+/**
+ * Validate that config has snap provider configuration.
+ *
+ * @param {import('../types/visual-diff-types').VisualRegressionConfig} config
+ * @throws {Error}
+ */
+function requireSnapConfig(config) {
+  if (!config.snap) {
+    throw new Error(
+      'Migration requires snap config in snapdrift.json. ' +
+      'Add a "snap" section with apiKeyEnv or apiKey.'
+    );
+  }
+}
+
+/**
+ * Run the migrate-to-snap direction.
+ * Reads local baselines and uploads them to Snap.
+ *
+ * @param {import('../types/visual-diff-types').VisualRegressionConfig} config
+ * @param {import('../types/visual-diff-types').CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runMigrateToSnap(config, opts) {
+  process.stdout.write(`Migrating baselines to Snap ...\n`);
+
+  requireSnapConfig(config);
+  const provider = createProvider('snap', config);
+  const baselineDir = opts.baselineDir;
+
+  const { results, manifest, screenshots, headSha } = await readLocalBaselines(baselineDir);
+
+  process.stdout.write(`Found ${screenshots.length} screenshot(s) for commit ${headSha.substring(0, 8)}\n`);
+
+  // Check idempotency — skip if baseline already exists
+  const existing = await provider.checkBaselineExists(headSha);
+  if (existing) {
+    process.stdout.write(`Baseline already exists for commit ${headSha.substring(0, 8)}. Skipping upload.\n`);
+    return;
+  }
+
+  const { uploaded, baselineId } = await provider.migrateBaselineFromLocal({
+    results,
+    manifest,
+    screenshots,
+    headSha
+  });
+
+  process.stdout.write(`Uploaded ${uploaded} screenshot(s) as baseline ${baselineId}\n`);
+}
+
+/**
+ * Run the migrate-to-local direction.
+ * Downloads baselines from Snap and writes them to the local directory.
+ *
+ * @param {import('../types/visual-diff-types').VisualRegressionConfig} config
+ * @param {import('../types/visual-diff-types').CliOptions} opts
+ * @returns {Promise<void>}
+ */
+export async function runMigrateToLocal(config, opts) {
+  process.stdout.write(`Migrating baselines from Snap to local ...\n`);
+
+  requireSnapConfig(config);
+  const provider = createProvider('snap', config);
+  const baselineDir = opts.baselineDir;
+
+  /** @type {{ results: object, manifest: object, screenshots: Array<{ filename: string, data: Buffer }>, engine: { name: string, version: string } }} */
+  let exported;
+  try {
+    exported = await provider.exportBaselines();
+  } catch (error) {
+    // Provide a clearer message for the stub case
+    if (error instanceof Error && error.message.includes('not yet available')) {
+      process.stderr.write(`Error: ${error.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+
+  // Engine compatibility check
+  const engineName = exported.engine?.name || 'unknown';
+  if (engineName !== 'snapdrift-local' && !opts.acceptCrossEngine) {
+    process.stderr.write(
+      `Error: Cannot import baselines captured by a different engine ("${engineName}").\n` +
+      `Baselines from a different capture engine may produce different screenshots, making comparison results unreliable.\n\n` +
+      `If you want to proceed anyway, re-run with --accept-cross-engine.\n` +
+      `This will override the engine name to "snapdrift-local" in the imported manifest, but visual differences may occur.\n`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  if (engineName !== 'snapdrift-local' && opts.acceptCrossEngine) {
+    process.stderr.write(
+      `Warning: Overriding engine name from "${engineName}" to "snapdrift-local". Visual differences may occur.\n`
+    );
+    if (exported.manifest && typeof exported.manifest === 'object') {
+      exported.manifest.captureProfile = exported.manifest.captureProfile || {};
+      exported.manifest.captureProfile.engine = exported.manifest.captureProfile.engine || {};
+      exported.manifest.captureProfile.engine.name = 'snapdrift-local';
+    }
+  }
+
+  // Write files
+  await fs.mkdir(baselineDir, { recursive: true });
+  await fs.mkdir(path.join(baselineDir, 'screenshots'), { recursive: true });
+
+  await fs.writeFile(path.join(baselineDir, 'results.json'), JSON.stringify(exported.results, null, 2));
+  await fs.writeFile(path.join(baselineDir, 'manifest.json'), JSON.stringify(exported.manifest, null, 2));
+
+  for (const screenshot of exported.screenshots) {
+    await fs.writeFile(path.join(baselineDir, 'screenshots', screenshot.filename), screenshot.data);
+  }
+
+  // Write migration metadata for idempotency tracking
+  await fs.writeFile(
+    path.join(baselineDir, '.migration-metadata.json'),
+    JSON.stringify({
+      source: 'snap',
+      migratedAt: new Date().toISOString(),
+      engine: exported.engine
+    }, null, 2)
+  );
+
+  process.stdout.write(`Downloaded ${exported.screenshots.length} screenshot(s) to ${baselineDir}\n`);
+}

package/lib/provider.mjs

@@ -0,0 +1,106 @@
+// @ts-check
+
+import { runBaselineCapture, generateDriftReport, stageArtifacts } from '@snapdrift/adapter-fs';
+import { buildReportCommentBody } from '@snapdrift/adapter-report-md';
+import { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError } 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').ProviderPublishBaselineResult} PublishBaselineResult */
+/** @typedef {import('../types/visual-diff-types').ProviderFetchBaselineOptions} FetchBaselineOptions */
+/** @typedef {import('../types/visual-diff-types').ProviderBaselineData} BaselineData */
+/** @typedef {import('../types/visual-diff-types').SnapConfig} SnapConfig */
+/** @typedef {import('../types/visual-diff-types').VisualRegressionConfig} VisualRegressionConfig */
+
+/**
+ * Local filesystem provider — wraps the current snapdrift behavior
+ * (Playwright capture, pixel diff, GH artifact baselines).
+ * @implements {VisualProvider}
+ */
+export class LocalProvider {
+  /**
+   * @param {CaptureOptions} options
+   * @returns {Promise<CaptureResult>}
+   */
+  async capture(options) {
+    return runBaselineCapture(options);
+  }
+
+  /**
+   * @param {DiffOptions} options
+   * @returns {Promise<DiffResult>}
+   */
+  async diff(options) {
+    return generateDriftReport(options);
+  }
+
+  /**
+   * @param {PublishBaselineOptions} options
+   * @returns {Promise<PublishBaselineResult>}
+   */
+  async publishBaseline(options) {
+    const { configPath: _unused, ...stageOpts } = options;
+    return stageArtifacts({ artifactType: 'baseline', ...stageOpts });
+  }
+
+  /**
+   * @param {FetchBaselineOptions} _options
+   * @returns {Promise<never>}
+   * @throws {Error} Not yet implemented for LocalProvider.
+   *   Use the pr-diff action for baseline resolution, or wait for a future release.
+   */
+  async fetchLatestBaseline(_options) {
+    throw new Error(
+      'LocalProvider.fetchLatestBaseline is not yet implemented. ' +
+      'Use the pr-diff action for baseline resolution, or wait for a future release.'
+    );
+  }
+
+  /**
+   * Build a PR comment body from a diff summary.
+   * LocalProvider omits the dashboard link (no dashboard exists).
+   *
+   * @param {Record<string, unknown>} summary
+   * @param {import('../types/visual-diff-types').ProviderCommentMeta} [meta]
+   * @returns {string}
+   */
+  buildCommentBody(summary, meta = {}) {
+    return buildReportCommentBody(summary, meta);
+  }
+}
+
+/** @type {Record<string, (config?: VisualRegressionConfig) => VisualProvider>} */
+const PROVIDER_FACTORIES = {
+  local: () => new LocalProvider(),
+  snap: (config) => {
+    if (!config?.snap) {
+      throw new Error('Snap provider requires snap configuration.');
+    }
+    return new SnapProvider(config.snap);
+  }
+};
+
+/**
+ * Create a VisualProvider instance by name.
+ *
+ * @param {string} providerName - Provider identifier ("local" or "snap")
+ * @param {VisualRegressionConfig} [config] - Full config (required for "snap" provider)
+ * @returns {VisualProvider}
+ * @throws {Error} If the provider name is not recognized
+ */
+export function createProvider(providerName, config) {
+  const factory = PROVIDER_FACTORIES[providerName];
+  if (!factory) {
+    throw new Error(
+      `Unknown SnapDrift provider: "${providerName}". ` +
+      `Available providers: ${Object.keys(PROVIDER_FACTORIES).join(', ')}.`
+    );
+  }
+  return factory(config);
+}
+
+export { SnapProvider, SnapApiError, SnapUnavailableError, SnapFallbackError, SnapSkipError };