@vizzly-testing/cli 0.30.0 → 0.32.0

package/dist/services/config-service.js

@@ -12,30 +12,10 @@ import { existsSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { cosmiconfigSync } from 'cosmiconfig';
+import { CONFIG_DEFAULTS } from '../config/core.js';
 import { loadGlobalConfig, saveGlobalConfig } from '../utils/global-config.js';
 import * as output from '../utils/output.js';
 
-/**
- * Default configuration values
- */
-let DEFAULT_CONFIG = {
-  comparison: {
-    threshold: 2.0,
-    minClusterSize: 2
-  },
-  server: {
-    port: 47392,
-    timeout: 30000
-  },
-  build: {
-    name: 'Build {timestamp}',
-    environment: 'test'
-  },
-  tdd: {
-    openReport: false
-  }
-};
-
 /**
  * Create a config service instance
  * @param {Object} options
@@ -76,9 +56,7 @@ export function createConfigService({
    * Get merged configuration with source tracking
    */
   async function getMergedConfig() {
-    let config = {
-      ...DEFAULT_CONFIG
-    };
+    let config = cloneConfigValue(CONFIG_DEFAULTS);
     let sources = {};
 
     // Layer 1: Global config
@@ -100,15 +78,15 @@ export function createConfigService({
 
     // Layer 3: Environment variables
     if (process.env.VIZZLY_THRESHOLD) {
-      config.comparison.threshold = parseFloat(process.env.VIZZLY_THRESHOLD);
+      config.comparison.threshold = Number(process.env.VIZZLY_THRESHOLD);
       sources.comparison = 'env';
     }
     if (process.env.VIZZLY_MIN_CLUSTER_SIZE) {
-      config.comparison.minClusterSize = parseInt(process.env.VIZZLY_MIN_CLUSTER_SIZE, 10);
+      config.comparison.minClusterSize = Number(process.env.VIZZLY_MIN_CLUSTER_SIZE);
       sources.comparison = 'env';
     }
     if (process.env.VIZZLY_PORT) {
-      config.server.port = parseInt(process.env.VIZZLY_PORT, 10);
+      config.server.port = Number(process.env.VIZZLY_PORT);
       sources.server = 'env';
     }
     return {
@@ -241,7 +219,7 @@ export default defineConfig(${JSON.stringify(newConfig, null, 2)});
     // Validate threshold
     if (config.comparison?.threshold !== undefined) {
       let threshold = config.comparison.threshold;
-      if (typeof threshold !== 'number' || threshold < 0) {
+      if (typeof threshold !== 'number' || !Number.isFinite(threshold) || threshold < 0) {
         errors.push('comparison.threshold must be a non-negative number');
       } else if (threshold > 100) {
         warnings.push('comparison.threshold above 100 may cause all comparisons to pass');
@@ -292,30 +270,44 @@ export default defineConfig(${JSON.stringify(newConfig, null, 2)});
  * Deep merge two objects
  */
 function mergeDeep(target, source) {
-  let result = {
-    ...target
-  };
+  let result = cloneConfigValue(target);
   for (let key in source) {
     if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
       result[key] = mergeDeep(result[key] || {}, source[key]);
+    } else if (Array.isArray(source[key])) {
+      result[key] = [...source[key]];
     } else {
       result[key] = source[key];
     }
   }
   return result;
 }
+function cloneConfigValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(cloneConfigValue);
+  }
+  if (value && typeof value === 'object') {
+    let clone = {};
+    for (let key in value) {
+      clone[key] = cloneConfigValue(value[key]);
+    }
+    return clone;
+  }
+  return value;
+}
 
 /**
  * Merge config with source tracking
  */
-function mergeWithTracking(target, source, sources, sourceName) {
+function mergeWithTracking(target, source, sources, sourceName, sectionName) {
   for (let key in source) {
+    let sourceSection = sectionName || key;
     if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
       if (!target[key]) target[key] = {};
-      mergeWithTracking(target[key], source[key], sources, sourceName);
+      mergeWithTracking(target[key], source[key], sources, sourceName, sourceSection);
     } else {
       target[key] = source[key];
-      sources[key] = sourceName;
+      sources[sourceSection] = sourceName;
     }
   }
 }

package/dist/services/index.js

@@ -9,7 +9,7 @@
  * This factory is only used by cli.js to provide services to plugins.
  */
 
-import { ServerManager } from './server-manager.js';
+import { createServerManager } from '../server-manager/index.js';
 import { TestRunner } from './test-runner.js';
 
 /**
@@ -26,9 +26,7 @@ import { TestRunner } from './test-runner.js';
  * @returns {Object} Services object for plugins
  */
 export function createServices(config) {
-  let serverManager = new ServerManager(config, {
-    services: {}
-  });
+  let serverManager = createServerManager(config, {});
   let testRunner = new TestRunner(config, serverManager);
   return {
     serverManager,

package/dist/services/static-report-generator.js

@@ -7,7 +7,7 @@
 
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 let __dirname = dirname(fileURLToPath(import.meta.url));
 
 /**
@@ -119,6 +119,13 @@ ${css}
 </body>
 </html>`;
 }
+export async function loadStaticReportRenderer(ssrModulePath = getSSRModulePath()) {
+  let moduleUrl = pathToFileURL(ssrModulePath).href;
+  let {
+    renderStaticReport
+  } = await import(moduleUrl);
+  return renderStaticReport;
+}
 
 /**
  * Generate a static report from the current TDD results
@@ -155,17 +162,9 @@ export async function generateStaticReport(workingDir, options = {}) {
 
     // Transform image URLs to relative paths
     let transformedData = transformImageUrls(reportData);
-
-    // Load and use the SSR module
-    let ssrModulePath = getSSRModulePath();
-    let {
-      renderStaticReport
-    } = await import(ssrModulePath);
+    let renderStaticReport = options.renderStaticReport || (await loadStaticReportRenderer());
     let renderedContent = renderStaticReport(transformedData);
-
-    // Get CSS
-    let reporterDistPath = getReporterDistPath();
-    let css = readFileSync(join(reporterDistPath, 'reporter-bundle.css'), 'utf8');
+    let css = options.css ?? readFileSync(join(getReporterDistPath(), 'reporter-bundle.css'), 'utf8');
 
     // Create output directory
     mkdirSync(outputDir, {
@@ -201,5 +200,5 @@ export async function generateStaticReport(workingDir, options = {}) {
  * Get the file:// URL for a report path
  */
 export function getReportFileUrl(reportPath) {
-  return `file://${reportPath}`;
+  return pathToFileURL(reportPath).href;
 }

package/dist/services/test-runner.js

@@ -2,16 +2,15 @@
  * Test Runner Service
  * Orchestrates the test execution flow
  *
- * This class is a thin wrapper around the functional operations in
- * src/test-runner/. It maintains backwards compatibility while
- * delegating to pure functions for testability.
+ * This EventEmitter adapter keeps the stable plugin-facing runner contract
+ * while delegating execution to the functional operations in src/test-runner/.
  */
 
 import { spawn } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import { createBuild as createApiBuild, createApiClient, finalizeBuild as finalizeApiBuild, getBuild } from '../api/index.js';
 import { VizzlyError } from '../errors/vizzly-error.js';
-import { cancelTests, createBuild, finalizeBuild, initializeDaemon, runTests } from '../test-runner/index.js';
+import { cancelTests, createBuild, fetchBuildUrl, finalizeBuild, initializeDaemon, runTests } from '../test-runner/index.js';
 import * as output from '../utils/output.js';
 import { writeSession as defaultWriteSession } from '../utils/session.js';
 import { createBuildObject } from './build-manager.js';
@@ -81,6 +80,7 @@ export class TestRunner extends EventEmitter {
     return result;
   }
   async createBuild(options, tdd) {
+    let createdApiBuild = null;
     let buildId = await createBuild({
       runOptions: options,
       tdd,
@@ -88,11 +88,23 @@ export class TestRunner extends EventEmitter {
       deps: {
         buildManager: this.buildManager,
         createApiClient: this.deps.createApiClient,
-        createApiBuild: this.deps.createApiBuild,
+        createApiBuild: async (client, payload) => {
+          createdApiBuild = await this.deps.createApiBuild(client, payload);
+          return createdApiBuild;
+        },
         output: this.deps.output
       }
     });
     if (!tdd && buildId) {
+      let buildUrl = createdApiBuild?.url || (await fetchBuildUrl({
+        buildId,
+        config: this.config,
+        deps: {
+          createApiClient: this.deps.createApiClient,
+          getBuild: this.deps.getBuild,
+          output: this.deps.output
+        }
+      }));
       let writeSession = this.deps.writeSession || defaultWriteSession;
       writeSession({
         buildId,
@@ -100,6 +112,10 @@ export class TestRunner extends EventEmitter {
         commit: options?.commit,
         parallelId: options?.parallelId
       });
+      this.emit('build-created', {
+        buildId,
+        url: buildUrl
+      });
     }
     return buildId;
   }
@@ -119,28 +135,6 @@ export class TestRunner extends EventEmitter {
       }
     });
   }
-  async executeTestCommand(testCommand, env) {
-    return new Promise((resolve, reject) => {
-      let proc = this.deps.spawn(testCommand, {
-        env,
-        stdio: 'inherit',
-        shell: true
-      });
-      this.testProcess = proc;
-      proc.on('error', error => {
-        reject(this.deps.createError(`Failed to run test command: ${error.message}`, 'TEST_COMMAND_FAILED'));
-      });
-      proc.on('exit', (code, signal) => {
-        if (signal === 'SIGINT') {
-          reject(this.deps.createError('Test command was interrupted', 'TEST_COMMAND_INTERRUPTED'));
-        } else if (code !== 0) {
-          reject(this.deps.createError(`Test command exited with code ${code}`, 'TEST_COMMAND_FAILED'));
-        } else {
-          resolve();
-        }
-      });
-    });
-  }
   async cancel() {
     await cancelTests({
       testProcess: this.testProcess,

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

@@ -9,6 +9,8 @@
  * 2D boxes that users have manually confirmed via the cloud UI.
  */
 
+let REGION_CENTER_TOLERANCE = 10;
+
 /**
  * Check if a diff cluster intersects with a region (2D box intersection)
  *
@@ -41,13 +43,77 @@ export function clusterIntersectsRegion(cluster, region) {
   let noOverlap = clusterX2 < region.x1 || clusterX1 > region.x2 || clusterY2 < region.y1 || clusterY1 > region.y2;
   return !noOverlap;
 }
+function normalizeBoundingBox(cluster) {
+  let box = cluster?.boundingBox || cluster;
+  if (!box) {
+    return null;
+  }
+  if (Number.isFinite(box.x) && Number.isFinite(box.y) && Number.isFinite(box.width) && Number.isFinite(box.height)) {
+    return {
+      x1: box.x,
+      y1: box.y,
+      x2: box.x + box.width,
+      y2: box.y + box.height,
+      width: Math.abs(box.width),
+      height: Math.abs(box.height)
+    };
+  }
+  if (Number.isFinite(box.x1) && Number.isFinite(box.y1) && Number.isFinite(box.x2) && Number.isFinite(box.y2)) {
+    let width = Math.abs(box.x2 - box.x1);
+    let height = Math.abs(box.y2 - box.y1);
+    return {
+      x1: box.x1,
+      y1: box.y1,
+      x2: box.x2,
+      y2: box.y2,
+      width,
+      height
+    };
+  }
+  return null;
+}
+function getBoundingBoxCenter(box) {
+  return {
+    x: (box.x1 + box.x2) / 2,
+    y: (box.y1 + box.y2) / 2
+  };
+}
+function getRegionLabel(region) {
+  return region.id || region.label || null;
+}
+function clusterMatchesRegion(cluster, region) {
+  let clusterBox = normalizeBoundingBox(cluster);
+  let regionBox = normalizeBoundingBox(region);
+  if (!clusterBox || !regionBox) {
+    return false;
+  }
+  let clusterCenter = getBoundingBoxCenter(clusterBox);
+  let regionCenter = getBoundingBoxCenter(regionBox);
+  let distance = Math.sqrt((clusterCenter.x - regionCenter.x) ** 2 + (clusterCenter.y - regionCenter.y) ** 2);
+  return distance <= REGION_CENTER_TOLERANCE;
+}
+function estimateClusterPixels(cluster) {
+  if (Number.isFinite(cluster?.pixelCount)) {
+    return cluster.pixelCount;
+  }
+  let box = normalizeBoundingBox(cluster);
+  if (!box) {
+    return 0;
+  }
+  return box.width * box.height * 0.5;
+}
 
 /**
- * Calculate what percentage of diff clusters fall within region boxes
+ * Calculate what percentage of changed pixels match confirmed regions.
+ *
+ * This mirrors cloud dynamic-region approval: clusters match confirmed regions
+ * by center proximity, then coverage is weighted by changed pixels. A huge
+ * unmatched change should not be hidden just because several tiny clusters
+ * match confirmed regions.
  *
  * @param {Array} diffClusters - Array of diff clusters from honeydiff
  * @param {Array} regions - Array of confirmed regions { x1, y1, x2, y2 }
- * @returns {{ coverage: number, clustersInRegions: number, totalClusters: number, matchedRegions: string[] }}
+ * @returns {{ coverage: number, clustersInRegions: number, totalClusters: number, matchedRegions: string[], pixelsInRegions: number, totalPixels: number }}
  */
 export function calculateRegionCoverage(diffClusters, regions) {
   if (!diffClusters || diffClusters.length === 0) {
@@ -55,7 +121,9 @@ export function calculateRegionCoverage(diffClusters, regions) {
       coverage: 0,
       clustersInRegions: 0,
       totalClusters: 0,
-      matchedRegions: []
+      matchedRegions: [],
+      pixelsInRegions: 0,
+      totalPixels: 0
     };
   }
   if (!regions || regions.length === 0) {
@@ -63,35 +131,41 @@ export function calculateRegionCoverage(diffClusters, regions) {
       coverage: 0,
       clustersInRegions: 0,
       totalClusters: diffClusters.length,
-      matchedRegions: []
+      matchedRegions: [],
+      pixelsInRegions: 0,
+      totalPixels: 0
     };
   }
   let clustersInRegions = 0;
   let matchedRegionIds = new Set();
+  let pixelsInRegions = 0;
+  let totalPixels = 0;
   for (let cluster of diffClusters) {
-    // Check if this cluster intersects any region
-    let intersectsAnyRegion = false;
+    let pixelCount = estimateClusterPixels(cluster);
+    totalPixels += pixelCount;
+    let matchedAnyRegion = false;
     for (let region of regions) {
-      if (clusterIntersectsRegion(cluster, region)) {
-        intersectsAnyRegion = true;
-        // Track which regions were matched (for debugging/display)
-        if (region.id) {
-          matchedRegionIds.add(region.id);
-        } else if (region.label) {
-          matchedRegionIds.add(region.label);
+      if (clusterMatchesRegion(cluster, region)) {
+        matchedAnyRegion = true;
+        let regionLabel = getRegionLabel(region);
+        if (regionLabel) {
+          matchedRegionIds.add(regionLabel);
         }
       }
     }
-    if (intersectsAnyRegion) {
+    if (matchedAnyRegion) {
       clustersInRegions++;
+      pixelsInRegions += pixelCount;
     }
   }
-  let coverage = clustersInRegions / diffClusters.length;
+  let coverage = totalPixels > 0 ? pixelsInRegions / totalPixels : 0;
   return {
     coverage,
     clustersInRegions,
     totalClusters: diffClusters.length,
-    matchedRegions: [...matchedRegionIds]
+    matchedRegions: [...matchedRegionIds],
+    pixelsInRegions,
+    totalPixels
   };
 }
 
@@ -99,17 +173,31 @@ export function calculateRegionCoverage(diffClusters, regions) {
  * Determine if a comparison should auto-pass based on region coverage
  *
  * Unlike hotspots which require confidence scoring, user-defined regions
- * are already confirmed by humans, so we only need the 80% threshold.
+ * are already confirmed by humans. Cloud still requires strong structural
+ * similarity so a layout shift cannot hide inside a confirmed box.
  *
  * @param {Array} regions - Confirmed regions (already filtered to confirmed status)
  * @param {{ coverage: number }} coverageResult - Result from calculateRegionCoverage
+ * @param {Object} options - Approval thresholds
+ * @param {number|null} options.ssimScore - Honeydiff SSIM/perceptual score
+ * @param {number} options.coverageThreshold - Required region coverage
+ * @param {number} options.ssimThreshold - Required structural similarity
  * @returns {boolean} True if diff should auto-pass as region-filtered
  */
-export function shouldAutoApproveFromRegions(regions, coverageResult) {
+export function shouldAutoApproveFromRegions(regions, coverageResult, options = {}) {
   if (!regions || regions.length === 0 || !coverageResult) {
     return false;
   }
-
-  // Need at least 80% of diff clusters in confirmed regions
-  return coverageResult.coverage >= 0.8;
+  let {
+    ssimScore = null,
+    coverageThreshold = 0.9,
+    ssimThreshold = 0.95
+  } = options;
+  if (coverageResult.coverage < coverageThreshold) {
+    return false;
+  }
+  if (ssimScore === null || ssimScore === undefined) {
+    return false;
+  }
+  return ssimScore >= ssimThreshold;
 }

package/dist/tdd/index.js

@@ -15,5 +15,5 @@ export { baselineMatchesSha, buildBaselineMetadataEntry, downloadBaselineImage,
 // 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 { downloadHotspots } from './services/hotspot-service.js';
 export { buildResults, calculateSummary, findComparison, findComparisonById, getErrorComparisons, getFailedComparisons, getNewComparisons, isSuccessful } from './services/result-service.js';

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

@@ -53,41 +53,4 @@ export function saveRegionMetadata(workingDir, regionData, summary = {}) {
     regions: regionData
   };
   writeFileSync(regionsPath, JSON.stringify(content, null, 2));
-}
-
-/**
- * Get regions 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} Region data or null if not available
- */
-export function getRegionsForScreenshot(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 = loadRegionMetadata(workingDir);
-    cache.loaded = true;
-  }
-  return cache.data?.[screenshotName] || null;
-}
-
-/**
- * Create an empty region cache object
- *
- * @returns {{ data: null, loaded: boolean }}
- */
-export function createRegionCache() {
-  return {
-    data: null,
-    loaded: false
-  };
 }

package/dist/tdd/runtime-context.js

@@ -0,0 +1,78 @@
+/**
+ * Runtime context assembly for TddService constructor.
+ * Keeps dependency merging and path bootstrap logic isolated and testable.
+ */
+
+export function buildTddDependencyOps(deps = {}, defaults = {}) {
+  let {
+    output = defaults.output,
+    colors = defaults.colors,
+    validatePathSecurity = defaults.validatePathSecurity,
+    initializeDirectories = defaults.initializeDirectories,
+    calculateHotspotCoverage = defaults.calculateHotspotCoverage,
+    fs = {},
+    api = {},
+    metadata = {},
+    baseline = {},
+    comparison = {},
+    signature = {},
+    results = {}
+  } = deps;
+  let fsOps = {
+    ...defaults.fs,
+    ...fs
+  };
+  let apiOps = {
+    ...defaults.api,
+    ...api
+  };
+  let metadataOps = {
+    ...defaults.metadata,
+    ...metadata
+  };
+  let baselineOps = {
+    ...defaults.baseline,
+    ...baseline
+  };
+  let comparisonOps = {
+    ...defaults.comparison,
+    ...comparison
+  };
+  let signatureOps = {
+    ...defaults.signature,
+    ...signature
+  };
+  let resultsOps = {
+    ...defaults.results,
+    ...results
+  };
+  let runtimeDeps = {
+    output,
+    colors,
+    validatePathSecurity,
+    initializeDirectories,
+    calculateHotspotCoverage,
+    ...fsOps,
+    ...apiOps,
+    ...metadataOps,
+    ...baselineOps,
+    ...comparisonOps,
+    ...signatureOps,
+    ...resultsOps
+  };
+  return {
+    runtimeDeps,
+    apiOps
+  };
+}
+export function resolveTddWorkingDirectory(workingDir, validatePathSecurity, output) {
+  try {
+    return validatePathSecurity(workingDir, workingDir);
+  } catch (error) {
+    output.error(`Invalid working directory: ${error.message}`);
+    throw new Error(`Working directory validation failed: ${error.message}`);
+  }
+}
+export function resolveTddPaths(workingDir, initializeDirectories) {
+  return initializeDirectories(workingDir);
+}