@vizzly-testing/cli 0.19.2 → 0.20.1-beta.0

package/dist/services/uploader.js

@@ -1,19 +1,20 @@
 /**
  * Vizzly Screenshot Uploader
  * Handles screenshot uploads to the Vizzly platform
+ *
+ * This module is a thin wrapper around the functional operations in
+ * src/uploader/. It maintains backwards compatibility while
+ * delegating to pure functions for testability.
  */
 
-import crypto from 'node:crypto';
 import { readFile, stat } from 'node:fs/promises';
-import { basename } from 'node:path';
 import { glob } from 'glob';
+import { checkShas, createApiClient, createBuild } from '../api/index.js';
 import { TimeoutError, UploadError, ValidationError } from '../errors/vizzly-error.js';
+import { resolveBatchSize, resolveTimeout } from '../uploader/index.js';
+import { upload as uploadOperation, waitForBuild as waitForBuildOperation } from '../uploader/operations.js';
 import { getDefaultBranch } from '../utils/git.js';
 import * as output from '../utils/output.js';
-import { ApiService } from './api-service.js';
-const DEFAULT_BATCH_SIZE = 50;
-const DEFAULT_SHA_CHECK_BATCH_SIZE = 100;
-const DEFAULT_TIMEOUT = 30000; // 30 seconds
 
 /**
  * Create a new uploader instance
@@ -25,378 +26,75 @@ export function createUploader({
   command,
   upload: uploadConfig = {}
 } = {}, options = {}) {
-  const signal = options.signal || new AbortController().signal;
-  const api = new ApiService({
+  let signal = options.signal || new AbortController().signal;
+  let client = createApiClient({
     baseUrl: apiUrl,
     token: apiKey,
     command: command || 'upload',
-    userAgent,
+    sdkUserAgent: userAgent,
     allowNoToken: true
   });
 
-  // Resolve tunable parameters from options or config
-  const batchSize = Number(options.batchSize ?? uploadConfig?.batchSize ?? DEFAULT_BATCH_SIZE);
-  const TIMEOUT_MS = Number(options.timeout ?? uploadConfig?.timeout ?? DEFAULT_TIMEOUT);
+  // Resolve tunable parameters
+  let batchSize = resolveBatchSize(options, uploadConfig);
+  let timeout = resolveTimeout(options, uploadConfig);
+
+  // Dependency injection for testing
+  let deps = options.deps || {
+    client,
+    createBuild,
+    getDefaultBranch,
+    glob,
+    readFile,
+    stat,
+    checkShas,
+    createError: (message, code, context) => {
+      let error = new UploadError(message, context);
+      error.code = code;
+      return error;
+    },
+    createValidationError: (message, context) => new ValidationError(message, context),
+    createUploadError: (message, context) => new UploadError(message, context),
+    createTimeoutError: (message, context) => new TimeoutError(message, context),
+    output
+  };
 
   /**
    * Upload screenshots to Vizzly
    */
-  async function upload({
-    screenshotsDir,
-    buildName,
-    branch,
-    commit,
-    message,
-    environment = 'production',
-    threshold,
-    pullRequestNumber,
-    parallelId,
-    onProgress = () => {}
-  }) {
-    try {
-      // Validate required config
-      if (!apiKey) {
-        throw new ValidationError('API key is required', {
-          config: {
-            apiKey,
-            apiUrl
-          }
-        });
-      }
-      if (!screenshotsDir) {
-        throw new ValidationError('Screenshots directory is required');
-      }
-      const stats = await stat(screenshotsDir);
-      if (!stats.isDirectory()) {
-        throw new ValidationError(`${screenshotsDir} is not a directory`);
-      }
-
-      // Find screenshots
-      const files = await findScreenshots(screenshotsDir);
-      if (files.length === 0) {
-        throw new UploadError('No screenshot files found', {
-          directory: screenshotsDir,
-          pattern: '**/*.png'
-        });
+  async function upload(uploadOptions) {
+    return uploadOperation({
+      uploadOptions,
+      config: {
+        apiKey,
+        apiUrl
+      },
+      signal,
+      batchSize,
+      deps: {
+        ...deps,
+        client: deps.client || client
       }
-      onProgress({
-        phase: 'scanning',
-        message: `Found ${files.length} screenshots`,
-        total: files.length
-      });
-
-      // Process files to get metadata
-      const fileMetadata = await processFiles(files, signal, current => onProgress({
-        phase: 'processing',
-        message: `Processing files`,
-        current,
-        total: files.length
-      }));
-
-      // Create build first to get buildId for SHA checking
-      const buildInfo = {
-        name: buildName || `Upload ${new Date().toISOString()}`,
-        branch: branch || (await getDefaultBranch()) || 'main',
-        commit_sha: commit,
-        commit_message: message,
-        environment,
-        threshold,
-        github_pull_request_number: pullRequestNumber,
-        parallel_id: parallelId
-      };
-      const build = await api.createBuild(buildInfo);
-      const buildId = build.id;
-
-      // Check which files need uploading (now with buildId)
-      const {
-        toUpload,
-        existing,
-        screenshots
-      } = await checkExistingFiles(fileMetadata, api, signal, buildId);
-      onProgress({
-        phase: 'deduplication',
-        message: `Checking for duplicates (${toUpload.length} to upload, ${existing.length} existing)`,
-        toUpload: toUpload.length,
-        existing: existing.length,
-        total: files.length
-      });
-
-      // Upload remaining files
-      const result = await uploadFiles({
-        toUpload,
-        existing,
-        screenshots,
-        buildId,
-        buildInfo,
-        api,
-        signal,
-        batchSize: batchSize,
-        onProgress: current => onProgress({
-          phase: 'uploading',
-          message: `Uploading screenshots`,
-          current,
-          total: toUpload.length
-        })
-      });
-      onProgress({
-        phase: 'completed',
-        message: `Upload completed`,
-        buildId: result.buildId,
-        url: result.url
-      });
-      return {
-        success: true,
-        buildId: result.buildId,
-        url: result.url,
-        stats: {
-          total: files.length,
-          uploaded: toUpload.length,
-          skipped: existing.length
-        }
-      };
-    } catch (error) {
-      output.debug('upload', 'failed', {
-        error: error.message
-      });
-
-      // Re-throw if already a VizzlyError
-      if (error.name?.includes('Error') && error.code) {
-        throw error;
-      }
-
-      // Wrap unknown errors
-      throw new UploadError(`Upload failed: ${error.message}`, {
-        originalError: error.message,
-        stack: error.stack
-      });
-    }
+    });
   }
 
   /**
    * Wait for a build to complete
    */
-  async function waitForBuild(buildId, timeout = TIMEOUT_MS) {
-    const startTime = Date.now();
-    while (Date.now() - startTime < timeout) {
-      if (signal.aborted) {
-        throw new UploadError('Operation cancelled', {
-          buildId
-        });
-      }
-      let resp;
-      try {
-        resp = await api.request(`/api/sdk/builds/${buildId}`, {
-          signal
-        });
-      } catch (err) {
-        const match = String(err?.message || '').match(/API request failed: (\d+)/);
-        const code = match ? match[1] : 'unknown';
-        throw new UploadError(`Failed to check build status: ${code}`);
-      }
-      const build = resp?.build ?? resp;
-      if (build.status === 'completed') {
-        // Extract comparison data for the response
-        const result = {
-          status: 'completed',
-          build
-        };
-
-        // Add comparison summary if available
-        if (typeof build.comparisonsTotal === 'number') {
-          result.comparisons = build.comparisonsTotal;
-          result.passedComparisons = build.comparisonsPassed || 0;
-          result.failedComparisons = build.comparisonsFailed || 0;
-        } else {
-          // Ensure failedComparisons is always a number, even when comparison data is missing
-          // This prevents the run command exit code check from failing
-          result.passedComparisons = 0;
-          result.failedComparisons = 0;
-        }
-
-        // Add build URL if available
-        if (build.url) {
-          result.url = build.url;
-        }
-        return result;
-      }
-      if (build.status === 'failed') {
-        throw new UploadError(`Build failed: ${build.error || 'Unknown error'}`);
-      }
-    }
-    throw new TimeoutError(`Build timed out after ${timeout}ms`, {
+  async function waitForBuild(buildId, waitTimeout = timeout) {
+    return waitForBuildOperation({
       buildId,
-      timeout,
-      elapsed: Date.now() - startTime
+      timeout: waitTimeout,
+      signal,
+      client: deps.client || client,
+      deps: {
+        createError: deps.createError,
+        createTimeoutError: deps.createTimeoutError
+      }
     });
   }
   return {
     upload,
     waitForBuild
   };
-}
-
-/**
- * Find all PNG screenshots in a directory
- */
-async function findScreenshots(directory) {
-  const pattern = `${directory}/**/*.png`;
-  return glob(pattern, {
-    absolute: true
-  });
-}
-
-/**
- * Process files to extract metadata and compute hashes
- */
-async function* processFilesGenerator(files, signal) {
-  for (const filePath of files) {
-    if (signal.aborted) throw new UploadError('Operation cancelled');
-    const buffer = await readFile(filePath);
-    const sha256 = crypto.createHash('sha256').update(buffer).digest('hex');
-    yield {
-      path: filePath,
-      filename: basename(filePath),
-      buffer,
-      sha256
-    };
-  }
-}
-async function processFiles(files, signal, onProgress) {
-  const results = [];
-  let count = 0;
-  for await (const file of processFilesGenerator(files, signal)) {
-    results.push(file);
-    count++;
-    if (count % 10 === 0 || count === files.length) {
-      onProgress(count);
-    }
-  }
-  return results;
-}
-
-/**
- * Check which files already exist on the server using signature-based deduplication
- */
-async function checkExistingFiles(fileMetadata, api, signal, buildId) {
-  const existingShas = new Set();
-  const allScreenshots = [];
-
-  // Check in batches using the new signature-based format
-  for (let i = 0; i < fileMetadata.length; i += DEFAULT_SHA_CHECK_BATCH_SIZE) {
-    if (signal.aborted) throw new UploadError('Operation cancelled');
-    const batch = fileMetadata.slice(i, i + DEFAULT_SHA_CHECK_BATCH_SIZE);
-
-    // Convert file metadata to screenshot objects with signature data
-    const screenshotBatch = batch.map(file => ({
-      sha256: file.sha256,
-      name: file.filename.replace(/\.png$/, ''),
-      // Remove .png extension for name
-      // Extract browser from filename if available (e.g., "homepage-chrome.png" -> "chrome")
-      browser: extractBrowserFromFilename(file.filename) || 'chrome',
-      // Default to chrome
-      // Default viewport dimensions (these could be extracted from filename or metadata if available)
-      viewport_width: 1920,
-      viewport_height: 1080
-    }));
-    try {
-      const res = await api.checkShas(screenshotBatch, buildId);
-      const {
-        existing = [],
-        screenshots = []
-      } = res || {};
-      for (let sha of existing) {
-        existingShas.add(sha);
-      }
-      allScreenshots.push(...screenshots);
-    } catch (error) {
-      // Continue without deduplication on error
-      console.debug('SHA check failed, continuing without deduplication:', error.message);
-    }
-  }
-  return {
-    toUpload: fileMetadata.filter(f => !existingShas.has(f.sha256)),
-    existing: fileMetadata.filter(f => existingShas.has(f.sha256)),
-    screenshots: allScreenshots
-  };
-}
-
-/**
- * Extract browser name from filename
- * @param {string} filename - The screenshot filename
- * @returns {string|null} Browser name or null if not found
- */
-function extractBrowserFromFilename(filename) {
-  const browsers = ['chrome', 'firefox', 'safari', 'edge', 'webkit'];
-  const lowerFilename = filename.toLowerCase();
-  for (const browser of browsers) {
-    if (lowerFilename.includes(browser)) {
-      return browser;
-    }
-  }
-  return null;
-}
-
-/**
- * Upload files to Vizzly
- */
-async function uploadFiles({
-  toUpload,
-  buildId,
-  api,
-  signal,
-  batchSize,
-  onProgress
-}) {
-  let result = null;
-
-  // If all files exist, screenshot records were already created during SHA check
-  if (toUpload.length === 0) {
-    return {
-      buildId,
-      url: null
-    }; // Build was already created
-  }
-
-  // Upload in batches
-  for (let i = 0; i < toUpload.length; i += batchSize) {
-    if (signal.aborted) throw new UploadError('Operation cancelled');
-    const batch = toUpload.slice(i, i + batchSize);
-    const form = new FormData();
-
-    // All batches add to existing build (build was created earlier)
-    form.append('build_id', buildId);
-
-    // Add files
-    for (const file of batch) {
-      const blob = new Blob([file.buffer], {
-        type: 'image/png'
-      });
-      form.append('screenshots', blob, file.filename);
-    }
-    try {
-      result = await api.request('/api/sdk/upload', {
-        method: 'POST',
-        body: form,
-        signal,
-        headers: {}
-      });
-    } catch (err) {
-      throw new UploadError(`Upload failed: ${err.message}`, {
-        batch: i / batchSize + 1
-      });
-    }
-    onProgress(i + batch.length);
-  }
-  return {
-    buildId,
-    url: result?.build?.url || result?.url
-  };
-}
-
-// createBuildWithExisting function removed - no longer needed since
-// builds are created first and /check-shas automatically creates screenshot records
-
-/**
- * Uploader class for handling screenshot uploads
- */
-// Legacy Uploader class removed — all functionality lives in createUploader.
+}

package/dist/tdd/core/hotspot-coverage.js

@@ -0,0 +1,112 @@
+/**
+ * Hotspot Coverage Calculation
+ *
+ * Pure functions for calculating how much of a visual diff falls within
+ * "hotspot" regions - areas of the UI that frequently change due to dynamic
+ * content (timestamps, animations, etc.).
+ *
+ * Uses 1D Y-coordinate matching (same algorithm as cloud).
+ */
+
+/**
+ * Calculate what percentage of diff falls within hotspot regions
+ *
+ * @param {Array} diffClusters - Array of diff clusters from honeydiff
+ * @param {Object} hotspotAnalysis - Hotspot data with regions array
+ * @returns {{ coverage: number, linesInHotspots: number, totalLines: number }}
+ */
+export function calculateHotspotCoverage(diffClusters, hotspotAnalysis) {
+  if (!diffClusters || diffClusters.length === 0) {
+    return {
+      coverage: 0,
+      linesInHotspots: 0,
+      totalLines: 0
+    };
+  }
+  if (!hotspotAnalysis || !hotspotAnalysis.regions || hotspotAnalysis.regions.length === 0) {
+    return {
+      coverage: 0,
+      linesInHotspots: 0,
+      totalLines: 0
+    };
+  }
+
+  // Extract Y-coordinates (diff lines) from clusters
+  // Each cluster has a boundingBox with y and height
+  let diffLines = [];
+  for (let cluster of diffClusters) {
+    if (cluster.boundingBox) {
+      let {
+        y,
+        height
+      } = cluster.boundingBox;
+      // Add all Y lines covered by this cluster
+      for (let line = y; line < y + height; line++) {
+        diffLines.push(line);
+      }
+    }
+  }
+  if (diffLines.length === 0) {
+    return {
+      coverage: 0,
+      linesInHotspots: 0,
+      totalLines: 0
+    };
+  }
+
+  // Remove duplicates and sort
+  diffLines = [...new Set(diffLines)].sort((a, b) => a - b);
+
+  // Check how many diff lines fall within hotspot regions
+  let linesInHotspots = 0;
+  for (let line of diffLines) {
+    let inHotspot = hotspotAnalysis.regions.some(region => line >= region.y1 && line <= region.y2);
+    if (inHotspot) {
+      linesInHotspots++;
+    }
+  }
+  let coverage = linesInHotspots / diffLines.length;
+  return {
+    coverage,
+    linesInHotspots,
+    totalLines: diffLines.length
+  };
+}
+
+/**
+ * Determine if a comparison should be filtered as "passed" based on hotspot coverage
+ *
+ * A diff is filtered when:
+ * 1. Coverage is >= 80% (most diff in hotspot regions)
+ * 2. Confidence is "high" or confidence score > 0.7
+ *
+ * @param {Object} hotspotAnalysis - Hotspot data with confidence info
+ * @param {{ coverage: number }} coverageResult - Result from calculateHotspotCoverage
+ * @returns {boolean} True if diff should be filtered as hotspot noise
+ */
+export function shouldFilterAsHotspot(hotspotAnalysis, coverageResult) {
+  if (!hotspotAnalysis || !coverageResult) {
+    return false;
+  }
+  let {
+    coverage
+  } = coverageResult;
+
+  // Need at least 80% of diff in hotspot regions
+  if (coverage < 0.8) {
+    return false;
+  }
+
+  // Need high confidence in the hotspot analysis
+  let {
+    confidence,
+    confidenceScore
+  } = hotspotAnalysis;
+  if (confidence === 'high') {
+    return true;
+  }
+  if (confidenceScore !== undefined && confidenceScore > 0.7) {
+    return true;
+  }
+  return false;
+}

package/dist/tdd/core/signature.js

@@ -0,0 +1,101 @@
+/**
+ * Screenshot Identity - Signature and Filename Generation
+ *
+ * CRITICAL: These functions MUST stay in sync with the cloud!
+ *
+ * Cloud counterpart: vizzly/src/utils/screenshot-identity.js
+ *   - generateScreenshotSignature()
+ *   - generateBaselineFilename()
+ *
+ * Contract tests: Both repos have golden tests that must produce identical values:
+ *   - Cloud: tests/contracts/signature-parity.test.js
+ *   - CLI:   tests/contracts/signature-parity.spec.js
+ *
+ * If you modify signature or filename generation here, you MUST:
+ *   1. Make the same change in the cloud repo
+ *   2. Update golden test values in BOTH repos
+ *   3. Run contract tests in both repos to verify parity
+ *
+ * The signature format is: name|viewport_width|browser|custom1|custom2|...
+ * The filename format is: {sanitized-name}_{12-char-sha256-hash}.png
+ */
+
+import crypto from 'node:crypto';
+
+/**
+ * Generate a screenshot signature for baseline matching
+ *
+ * SYNC WITH: vizzly/src/utils/screenshot-identity.js - generateScreenshotSignature()
+ *
+ * Uses same logic as cloud: name + viewport_width + browser + custom properties
+ *
+ * @param {string} name - Screenshot name
+ * @param {Object} properties - Screenshot properties (viewport, browser, metadata, etc.)
+ * @param {Array<string>} customProperties - Custom property names from project settings
+ * @returns {string} Signature like "Login|1920|chrome|iPhone 15 Pro"
+ */
+export function generateScreenshotSignature(name, properties = {}, customProperties = []) {
+  // Match cloud screenshot-identity.js behavior exactly:
+  // Always include all default properties (name, viewport_width, browser)
+  // even if null/undefined, using empty string as placeholder
+  let defaultProperties = ['name', 'viewport_width', 'browser'];
+  let allProperties = [...defaultProperties, ...customProperties];
+  let parts = allProperties.map(propName => {
+    let value;
+    if (propName === 'name') {
+      value = name;
+    } else if (propName === 'viewport_width') {
+      // Check for viewport_width as top-level property first (backend format)
+      value = properties.viewport_width;
+      // Fallback to nested viewport.width (SDK format)
+      if (value === null || value === undefined) {
+        value = properties.viewport?.width;
+      }
+    } else if (propName === 'browser') {
+      value = properties.browser;
+    } else {
+      // Custom property - check multiple locations
+      value = properties[propName] ?? properties.metadata?.[propName] ?? properties.metadata?.properties?.[propName];
+    }
+
+    // Handle null/undefined values consistently (match cloud behavior)
+    if (value === null || value === undefined) {
+      return '';
+    }
+
+    // Convert to string and normalize
+    return String(value).trim();
+  });
+  return parts.join('|');
+}
+
+/**
+ * Generate a stable, filesystem-safe filename for a screenshot baseline
+ * Uses a hash of the signature to avoid character encoding issues
+ * Matches the cloud's generateBaselineFilename implementation exactly
+ *
+ * @param {string} name - Screenshot name
+ * @param {string} signature - Full signature string
+ * @returns {string} Filename like "homepage_a1b2c3d4e5f6.png"
+ */
+export function generateBaselineFilename(name, signature) {
+  let hash = crypto.createHash('sha256').update(signature).digest('hex').slice(0, 12);
+
+  // Sanitize the name for filesystem safety
+  let safeName = name.replace(/[/\\:*?"<>|]/g, '') // Remove unsafe chars
+  .replace(/\s+/g, '-') // Spaces to hyphens
+  .slice(0, 50); // Limit length
+
+  return `${safeName}_${hash}.png`;
+}
+
+/**
+ * Generate a stable unique ID from signature for TDD comparisons
+ * This allows UI to reference specific variants without database IDs
+ *
+ * @param {string} signature - Full signature string
+ * @returns {string} 16-char hex hash
+ */
+export function generateComparisonId(signature) {
+  return crypto.createHash('sha256').update(signature).digest('hex').slice(0, 16);
+}

package/dist/tdd/index.js

@@ -0,0 +1,19 @@
+/**
+ * TDD Module Exports
+ *
+ * Re-exports all TDD functionality for clean imports.
+ */
+
+export { calculateHotspotCoverage, shouldFilterAsHotspot } from './core/hotspot-coverage.js';
+// Core pure functions
+export { generateBaselineFilename, generateComparisonId, generateScreenshotSignature } from './core/signature.js';
+
+// Metadata I/O
+export { createEmptyBaselineMetadata, findScreenshotBySignature, loadBaselineMetadata, saveBaselineMetadata, upsertScreenshotInMetadata } from './metadata/baseline-metadata.js';
+export { createHotspotCache, getHotspotForScreenshot, loadHotspotMetadata, saveHotspotMetadata } from './metadata/hotspot-metadata.js';
+export { baselineMatchesSha, buildBaselineMetadataEntry, downloadBaselineImage, downloadBaselinesInBatches } from './services/baseline-downloader.js';
+// Services
+export { baselineExists, clearBaselineData, getBaselinePath, getCurrentPath, getDiffPath, initializeDirectories, promoteCurrentToBaseline, readBaseline, readCurrent, saveBaseline, saveCurrent } from './services/baseline-manager.js';
+export { buildErrorComparison, buildFailedComparison, buildNewComparison, buildPassedComparison, compareImages, isDimensionMismatchError } from './services/comparison-service.js';
+export { downloadHotspots, extractScreenshotNames } from './services/hotspot-service.js';
+export { buildResults, calculateSummary, findComparison, findComparisonById, getErrorComparisons, getFailedComparisons, getNewComparisons, isSuccessful } from './services/result-service.js';