@vizzly-testing/cli 0.20.0 → 0.20.1-beta.1

package/dist/tdd/metadata/baseline-metadata.js

@@ -0,0 +1,103 @@
+/**
+ * Baseline Metadata I/O
+ *
+ * Functions for reading and writing baseline metadata.json files.
+ * These handle the local storage of baseline information.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Load baseline metadata from disk
+ *
+ * @param {string} baselinePath - Path to baselines directory
+ * @returns {Object|null} Baseline metadata or null if not found
+ */
+export function loadBaselineMetadata(baselinePath) {
+  let metadataPath = join(baselinePath, 'metadata.json');
+  if (!existsSync(metadataPath)) {
+    return null;
+  }
+  try {
+    let content = readFileSync(metadataPath, 'utf8');
+    return JSON.parse(content);
+  } catch (error) {
+    // Log for debugging but return null - caller can handle missing metadata
+    console.debug?.(`Failed to parse baseline metadata: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save baseline metadata to disk
+ *
+ * @param {string} baselinePath - Path to baselines directory
+ * @param {Object} metadata - Metadata object to save
+ */
+export function saveBaselineMetadata(baselinePath, metadata) {
+  // Ensure directory exists
+  if (!existsSync(baselinePath)) {
+    mkdirSync(baselinePath, {
+      recursive: true
+    });
+  }
+  let metadataPath = join(baselinePath, 'metadata.json');
+  writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
+}
+
+/**
+ * Create empty baseline metadata structure
+ *
+ * @param {Object} options - Options for the baseline
+ * @param {number} options.threshold - Comparison threshold
+ * @param {string[]} options.signatureProperties - Custom signature properties
+ * @returns {Object} Empty baseline metadata
+ */
+export function createEmptyBaselineMetadata(options = {}) {
+  return {
+    buildId: 'local-baseline',
+    buildName: 'Local TDD Baseline',
+    environment: 'test',
+    branch: 'local',
+    threshold: options.threshold ?? 2.0,
+    signatureProperties: options.signatureProperties ?? [],
+    createdAt: new Date().toISOString(),
+    screenshots: []
+  };
+}
+
+/**
+ * Update or add a screenshot entry in the metadata
+ *
+ * @param {Object} metadata - Baseline metadata object (mutated)
+ * @param {Object} screenshotEntry - Screenshot entry to upsert
+ * @param {string} signature - Signature to match for updates
+ * @returns {Object} The updated metadata (same reference)
+ */
+export function upsertScreenshotInMetadata(metadata, screenshotEntry, signature) {
+  if (!metadata.screenshots) {
+    metadata.screenshots = [];
+  }
+  let existingIndex = metadata.screenshots.findIndex(s => s.signature === signature);
+  if (existingIndex >= 0) {
+    metadata.screenshots[existingIndex] = screenshotEntry;
+  } else {
+    metadata.screenshots.push(screenshotEntry);
+  }
+  return metadata;
+}
+
+/**
+ * Find a screenshot in metadata by signature
+ *
+ * @param {Object} metadata - Baseline metadata object
+ * @param {string} signature - Signature to find
+ * @returns {Object|null} Screenshot entry or null if not found
+ */
+export function findScreenshotBySignature(metadata, signature) {
+  if (!metadata?.screenshots) {
+    return null;
+  }
+  return metadata.screenshots.find(s => s.signature === signature) || null;
+}

package/dist/tdd/metadata/hotspot-metadata.js

@@ -0,0 +1,93 @@
+/**
+ * Hotspot Metadata I/O
+ *
+ * Functions for reading and writing hotspot data files.
+ * Hotspots identify regions of screenshots that frequently change
+ * due to dynamic content (timestamps, animations, etc.).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Load hotspot data from disk
+ *
+ * @param {string} workingDir - Working directory containing .vizzly folder
+ * @returns {Object|null} Hotspot data keyed by screenshot name, or null if not found
+ */
+export function loadHotspotMetadata(workingDir) {
+  let hotspotsPath = join(workingDir, '.vizzly', 'hotspots.json');
+  if (!existsSync(hotspotsPath)) {
+    return null;
+  }
+  try {
+    let content = readFileSync(hotspotsPath, 'utf8');
+    let data = JSON.parse(content);
+    return data.hotspots || null;
+  } catch {
+    // Return null for parse/read errors
+    return null;
+  }
+}
+
+/**
+ * Save hotspot data to disk
+ *
+ * @param {string} workingDir - Working directory containing .vizzly folder
+ * @param {Object} hotspotData - Hotspot data keyed by screenshot name
+ * @param {Object} summary - Summary information about the hotspots
+ */
+export function saveHotspotMetadata(workingDir, hotspotData, summary = {}) {
+  let vizzlyDir = join(workingDir, '.vizzly');
+
+  // Ensure directory exists
+  if (!existsSync(vizzlyDir)) {
+    mkdirSync(vizzlyDir, {
+      recursive: true
+    });
+  }
+  let hotspotsPath = join(vizzlyDir, 'hotspots.json');
+  let content = {
+    downloadedAt: new Date().toISOString(),
+    summary,
+    hotspots: hotspotData
+  };
+  writeFileSync(hotspotsPath, JSON.stringify(content, null, 2));
+}
+
+/**
+ * Get hotspot for a specific screenshot with caching support
+ *
+ * This is a pure function that takes a cache object as parameter
+ * for stateless operation. The cache is mutated if data needs to be loaded.
+ *
+ * @param {Object} cache - Cache object { data: Object|null, loaded: boolean }
+ * @param {string} workingDir - Working directory
+ * @param {string} screenshotName - Name of the screenshot
+ * @returns {Object|null} Hotspot analysis or null if not available
+ */
+export function getHotspotForScreenshot(cache, workingDir, screenshotName) {
+  // Check cache first
+  if (cache.data?.[screenshotName]) {
+    return cache.data[screenshotName];
+  }
+
+  // Load from disk if not yet loaded
+  if (!cache.loaded) {
+    cache.data = loadHotspotMetadata(workingDir);
+    cache.loaded = true;
+  }
+  return cache.data?.[screenshotName] || null;
+}
+
+/**
+ * Create an empty hotspot cache object
+ *
+ * @returns {{ data: null, loaded: boolean }}
+ */
+export function createHotspotCache() {
+  return {
+    data: null,
+    loaded: false
+  };
+}

package/dist/tdd/services/baseline-downloader.js

@@ -0,0 +1,151 @@
+/**
+ * Baseline Downloader
+ *
+ * Functions for downloading baseline images from the cloud API.
+ * These are lower-level utilities - orchestration happens in TddService.
+ */
+
+import { existsSync, writeFileSync } from 'node:fs';
+import { fetchWithTimeout } from '../../utils/fetch-utils.js';
+
+/**
+ * Download a single baseline image
+ *
+ * @param {string} url - URL to download from
+ * @param {string} destPath - Destination file path
+ * @param {Object} options - Options
+ * @param {number} options.timeout - Request timeout in ms (default: 30000)
+ * @returns {Promise<{ success: boolean, error?: string }>}
+ */
+export async function downloadBaselineImage(url, destPath, options = {}) {
+  let {
+    timeout = 30000
+  } = options;
+  try {
+    let response = await fetchWithTimeout(url, {
+      timeout
+    });
+    if (!response.ok) {
+      return {
+        success: false,
+        error: `HTTP ${response.status}: ${response.statusText}`
+      };
+    }
+    let buffer = Buffer.from(await response.arrayBuffer());
+    writeFileSync(destPath, buffer);
+    return {
+      success: true
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+}
+
+/**
+ * Check if a baseline already exists with matching SHA
+ *
+ * @param {string} filePath - Path to the baseline file
+ * @param {string} expectedSha - Expected SHA256 hash
+ * @param {Map<string, string>} shaMap - Map of filename -> sha256
+ * @returns {boolean}
+ */
+export function baselineMatchesSha(filePath, expectedSha, shaMap) {
+  if (!existsSync(filePath) || !expectedSha) {
+    return false;
+  }
+  let filename = filePath.split('/').pop();
+  let storedSha = shaMap.get(filename);
+  return storedSha === expectedSha;
+}
+
+/**
+ * Download multiple baselines in batches
+ *
+ * @param {Array} screenshots - Screenshots to download
+ * @param {Object} options - Options
+ * @param {string} options.baselinePath - Path to baselines directory
+ * @param {Map<string, string>} options.existingShaMap - Existing SHA map for skip logic
+ * @param {number} options.batchSize - Concurrent downloads (default: 5)
+ * @param {Function} options.onProgress - Progress callback (downloaded, skipped, errors, total)
+ * @param {Function} options.getFilePath - Function to get file path for a screenshot
+ * @returns {Promise<{ downloaded: number, skipped: number, errors: number }>}
+ */
+export async function downloadBaselinesInBatches(screenshots, options = {}) {
+  let {
+    existingShaMap = new Map(),
+    batchSize = 5,
+    onProgress,
+    getFilePath
+  } = options;
+  let downloaded = 0;
+  let skipped = 0;
+  let errors = 0;
+  let total = screenshots.length;
+
+  // Process in batches
+  for (let i = 0; i < screenshots.length; i += batchSize) {
+    let batch = screenshots.slice(i, i + batchSize);
+    let batchPromises = batch.map(async screenshot => {
+      let filePath = getFilePath(screenshot);
+      let url = screenshot.original_url;
+      if (!url) {
+        errors++;
+        return;
+      }
+
+      // Skip if SHA matches
+      if (baselineMatchesSha(filePath, screenshot.sha256, existingShaMap)) {
+        skipped++;
+        downloaded++;
+        return;
+      }
+      let result = await downloadBaselineImage(url, filePath);
+      if (result.success) {
+        downloaded++;
+      } else {
+        errors++;
+      }
+    });
+    await Promise.all(batchPromises);
+    if (onProgress) {
+      onProgress(downloaded, skipped, errors, total);
+    }
+  }
+  return {
+    downloaded,
+    skipped,
+    errors
+  };
+}
+
+/**
+ * Build baseline metadata entry for a downloaded screenshot
+ *
+ * @param {Object} screenshot - Screenshot data from API
+ * @param {string} filename - Local filename
+ * @param {string} filePath - Full file path
+ * @param {Object} buildInfo - Build information
+ * @returns {Object} Metadata entry
+ */
+export function buildBaselineMetadataEntry(screenshot, filename, filePath, buildInfo = {}) {
+  return {
+    name: screenshot.name,
+    originalName: screenshot.name,
+    sha256: screenshot.sha256,
+    id: screenshot.id,
+    filename,
+    path: filePath,
+    browser: screenshot.browser || screenshot.metadata?.browser,
+    viewport_width: screenshot.viewport_width || screenshot.metadata?.viewport?.width || screenshot.properties?.viewport?.width,
+    originalUrl: screenshot.original_url,
+    fileSize: screenshot.file_size,
+    dimensions: screenshot.dimensions,
+    // Build info for tracking
+    buildId: buildInfo.buildId,
+    commitSha: buildInfo.commitSha,
+    approvalStatus: screenshot.approval_status
+  };
+}

package/dist/tdd/services/baseline-manager.js

@@ -0,0 +1,166 @@
+/**
+ * Baseline Manager
+ *
+ * Local baseline CRUD operations - manages the file system aspects
+ * of baseline storage without any network operations.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Initialize TDD directory structure
+ *
+ * @param {string} workingDir - Working directory
+ * @returns {{ baselinePath: string, currentPath: string, diffPath: string }}
+ */
+export function initializeDirectories(workingDir) {
+  let vizzlyDir = join(workingDir, '.vizzly');
+  let baselinePath = join(vizzlyDir, 'baselines');
+  let currentPath = join(vizzlyDir, 'current');
+  let diffPath = join(vizzlyDir, 'diffs');
+  for (let dir of [baselinePath, currentPath, diffPath]) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, {
+        recursive: true
+      });
+    }
+  }
+  return {
+    baselinePath,
+    currentPath,
+    diffPath
+  };
+}
+
+/**
+ * Clear all baseline data for fresh download
+ *
+ * @param {{ baselinePath: string, currentPath: string, diffPath: string }} paths
+ */
+export function clearBaselineData(paths) {
+  let {
+    baselinePath,
+    currentPath,
+    diffPath
+  } = paths;
+  for (let dir of [baselinePath, currentPath, diffPath]) {
+    if (existsSync(dir)) {
+      rmSync(dir, {
+        recursive: true,
+        force: true
+      });
+      mkdirSync(dir, {
+        recursive: true
+      });
+    }
+  }
+}
+
+/**
+ * Save an image as baseline
+ *
+ * @param {string} baselinePath - Path to baselines directory
+ * @param {string} filename - Filename for the baseline
+ * @param {Buffer} imageBuffer - Image data
+ */
+export function saveBaseline(baselinePath, filename, imageBuffer) {
+  let filePath = join(baselinePath, filename);
+  writeFileSync(filePath, imageBuffer);
+}
+
+/**
+ * Save current screenshot
+ *
+ * @param {string} currentPath - Path to current screenshots directory
+ * @param {string} filename - Filename for the screenshot
+ * @param {Buffer} imageBuffer - Image data
+ * @returns {string} Full path to saved file
+ */
+export function saveCurrent(currentPath, filename, imageBuffer) {
+  let filePath = join(currentPath, filename);
+  writeFileSync(filePath, imageBuffer);
+  return filePath;
+}
+
+/**
+ * Check if baseline exists for a filename
+ *
+ * @param {string} baselinePath - Path to baselines directory
+ * @param {string} filename - Filename to check
+ * @returns {boolean}
+ */
+export function baselineExists(baselinePath, filename) {
+  return existsSync(join(baselinePath, filename));
+}
+
+/**
+ * Get full path to a baseline file
+ *
+ * @param {string} baselinePath - Path to baselines directory
+ * @param {string} filename - Filename
+ * @returns {string}
+ */
+export function getBaselinePath(baselinePath, filename) {
+  return join(baselinePath, filename);
+}
+
+/**
+ * Get full path to a current file
+ *
+ * @param {string} currentPath - Path to current screenshots directory
+ * @param {string} filename - Filename
+ * @returns {string}
+ */
+export function getCurrentPath(currentPath, filename) {
+  return join(currentPath, filename);
+}
+
+/**
+ * Get full path to a diff file
+ *
+ * @param {string} diffPath - Path to diffs directory
+ * @param {string} filename - Filename
+ * @returns {string}
+ */
+export function getDiffPath(diffPath, filename) {
+  return join(diffPath, filename);
+}
+
+/**
+ * Promote current screenshot to baseline (accept as new baseline)
+ *
+ * @param {string} currentPath - Path to current screenshots directory
+ * @param {string} baselinePath - Path to baselines directory
+ * @param {string} filename - Filename
+ */
+export function promoteCurrentToBaseline(currentPath, baselinePath, filename) {
+  let currentFile = join(currentPath, filename);
+  let baselineFile = join(baselinePath, filename);
+  if (!existsSync(currentFile)) {
+    throw new Error(`Current screenshot not found: ${currentFile}`);
+  }
+  copyFileSync(currentFile, baselineFile);
+}
+
+/**
+ * Read baseline image
+ *
+ * @param {string} baselinePath - Path to baselines directory
+ * @param {string} filename - Filename
+ * @returns {Buffer}
+ */
+export function readBaseline(baselinePath, filename) {
+  return readFileSync(join(baselinePath, filename));
+}
+
+/**
+ * Read current screenshot
+ *
+ * @param {string} currentPath - Path to current screenshots directory
+ * @param {string} filename - Filename
+ * @returns {Buffer}
+ */
+export function readCurrent(currentPath, filename) {
+  return readFileSync(join(currentPath, filename));
+}