snapdrift 0.2.1 → 0.4.0

package/lib/drift-summary.mjs

@@ -1,156 +1,5 @@
 // @ts-check
+// Re-exports from packages — this module is a thin shim.
 
-import fs from 'node:fs/promises';
-import path from 'node:path';
-
-import { splitCommaList } from './snapdrift-config.mjs';
-
-const DEFAULT_OUT_DIR = path.join('qa-artifacts', 'snapdrift', 'drift', 'current');
-const DEFAULT_SNAPDRIFT_REPO_URL = 'https://github.com/ranacseruet/snapdrift';
-const DEFAULT_SNAPDRIFT_ICON_URL = 'https://raw.githubusercontent.com/ranacseruet/snapdrift/main/assets/snapdrift-logo-icon.png';
-
-const STATUS_ICONS = {
-  clean: '✅',
-  'changes-detected': '🟡',
-  incomplete: '⚠️',
-  skipped: '⏭️'
-};
-
-const STATUS_LABELS = {
-  clean: 'Clean',
-  'changes-detected': 'Drift detected',
-  incomplete: 'Incomplete',
-  skipped: 'Skipped'
-};
-
-/**
- * @param {string} reason
- * @returns {{ message: string, markdownReason: string }}
- */
-function describeReason(reason) {
-  if (reason === 'missing_main_baseline_artifact') {
-    return {
-      message: 'The latest successful `main` SnapDrift baseline was not available.',
-      markdownReason: 'latest successful `main` SnapDrift baseline was not available'
-    };
-  }
-
-  if (reason === 'no_snapdrift_relevant_changes') {
-    return {
-      message: 'No drift-relevant changes were detected in this pull request.',
-      markdownReason: 'no drift-relevant changes were detected in this pull request'
-    };
-  }
-
-  const text = reason.replace(/_/g, ' ');
-  return {
-    message: text,
-    markdownReason: text
-  };
-}
-
-/**
- * @param {{
- *   status?: 'skipped' | 'clean' | 'changes-detected' | 'incomplete',
- *   reason: string,
- *   message?: string,
- *   selectedRouteIds?: string[] | string,
- *   currentResultsPath?: string,
- *   baselineAvailable?: boolean
- * }} options
- * @returns {{ summary: Record<string, unknown>, markdown: string }}
- */
-export function buildDriftSummary(options) {
-  const description = describeReason(options.reason);
-  const status = options.status || 'skipped';
-  const selectedRoutes = Array.isArray(options.selectedRouteIds)
-    ? options.selectedRouteIds
-    : splitCommaList(options.selectedRouteIds);
-  const message = options.message || description.message;
-  const statusIcon = STATUS_ICONS[status] || '⚠️';
-  const statusLabel = STATUS_LABELS[status] || status;
-  const baselineAvailable = typeof options.baselineAvailable === 'boolean'
-    ? String(options.baselineAvailable)
-    : 'n/a';
-  const currentCapture = options.currentResultsPath
-    ? `\`${options.currentResultsPath}\``
-    : 'n/a';
-
-  /** @type {Record<string, unknown>} */
-  const summary = {
-    status,
-    reason: options.reason,
-    message,
-    selectedRoutes
-  };
-
-  if (typeof options.baselineAvailable === 'boolean') {
-    summary.baselineAvailable = options.baselineAvailable;
-  }
-  if (options.currentResultsPath) {
-    summary.currentResultsPath = options.currentResultsPath;
-  }
-
-  const lines = [
-    `<img src="${DEFAULT_SNAPDRIFT_ICON_URL}" alt="SnapDrift" width="24" height="24" />`,
-    '',
-    `# ${statusIcon} SnapDrift Report — ${statusLabel}`,
-    '',
-    '| Selected routes | Baseline available | Current capture |',
-    '|---------------:|:-------------------|:----------------|',
-    `| ${selectedRoutes.length} | ${baselineAvailable} | ${currentCapture} |`
-  ];
-
-  lines.push('');
-  lines.push(`> **Reason:** ${description.markdownReason}`);
-  lines.push(`> **Details:** ${message}`);
-
-  if (options.reason === 'missing_main_baseline_artifact') {
-    lines.push('');
-    lines.push('## Next action');
-    lines.push('');
-    lines.push('- Publish or refresh a SnapDrift baseline on `main`, then rerun the pull request check.');
-  }
-
-  lines.push('');
-  lines.push(`<div align="right"><sub>Powered by <a href="${DEFAULT_SNAPDRIFT_REPO_URL}">SnapDrift</a></sub></div>`);
-
-  return {
-    summary,
-    markdown: `${lines.join('\n')}\n`
-  };
-}
-
-/**
- * @param {{
- *   status?: 'skipped' | 'clean' | 'changes-detected' | 'incomplete',
- *   reason: string,
- *   message?: string,
- *   selectedRouteIds?: string[] | string,
- *   currentResultsPath?: string,
- *   baselineAvailable?: boolean,
- *   outDir?: string,
- *   summaryPath?: string,
- *   markdownPath?: string
- * }} options
- * @returns {Promise<{ summaryPath: string, markdownPath: string, summary: Record<string, unknown>, markdown: string }>}
- */
-export async function writeDriftSummary(options) {
-  const resolvedOutDir = path.resolve(options.outDir || DEFAULT_OUT_DIR);
-  const resolvedSummaryPath = path.resolve(options.summaryPath || path.join(resolvedOutDir, 'summary.json'));
-  const resolvedMarkdownPath = path.resolve(options.markdownPath || path.join(resolvedOutDir, 'summary.md'));
-  const { summary, markdown } = buildDriftSummary(options);
-
-  await fs.mkdir(resolvedOutDir, { recursive: true });
-  await Promise.all([
-    fs.writeFile(resolvedSummaryPath, `${JSON.stringify(summary, null, 2)}\n`),
-    fs.writeFile(resolvedMarkdownPath, markdown)
-  ]);
-
-  return {
-    summaryPath: resolvedSummaryPath,
-    markdownPath: resolvedMarkdownPath,
-    summary,
-    markdown
-  };
-}
+export { buildDriftSummary } from '@snapdrift/adapter-report-md';
+export { writeDriftSummary } from '@snapdrift/adapter-fs';

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