devlens-mcp 0.3.0

package/src/utils/image-preprocess.ts

@@ -0,0 +1,430 @@
+import sharp from "sharp";
+import { PNG } from "pngjs";
+
+/**
+ * Image preprocessing utilities for removing Figma presentation artifacts
+ * 
+ * Handles:
+ * - Rounded corners from Figma frame exports
+ * - Grey/black backgrounds and borders
+ * - Uniform colored bars (top/bottom/sides)
+ * - Transparent padding around content
+ */
+
+export interface PreprocessOptions {
+  /** Strategy to use for artifact removal */
+  strategy?: "auto" | "trim" | "alpha" | "content" | "none";
+  /** Threshold for trim strategy (0-255, default 10) */
+  trimThreshold?: number;
+  /** Whether to apply additional trim after content detection */
+  aggressiveTrim?: boolean;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+
+export interface PreprocessResult {
+  /** Processed image buffer */
+  buffer: Buffer;
+  /** Strategy that was applied (may include variant info like "auto-content" or "trim") */
+  appliedStrategy: string;
+  /** Artifacts that were detected and removed */
+  artifactsRemoved: string[];
+  /** Original dimensions */
+  originalDimensions: { width: number; height: number };
+  /** Final dimensions after preprocessing */
+  finalDimensions: { width: number; height: number };
+  /** Crop information */
+  cropInfo: { left: number; top: number; width: number; height: number };
+}
+
+interface ContentBounds {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Analyze image edges to detect uniform borders or bars
+ */
+async function analyzeEdges(buffer: Buffer): Promise<{
+  hasUniformBorder: boolean;
+  avgCornerColor: { r: number; g: number; b: number; a: number };
+  isDarkBorder: boolean;
+  isLightBorder: boolean;
+}> {
+  const png = PNG.sync.read(buffer);
+  const { width, height } = png;
+  
+  // Sample corner pixels (50x50 region in top-left)
+  const cornerSize = Math.min(50, Math.floor(width / 4), Math.floor(height / 4));
+  const cornerPixels: Array<{ r: number; g: number; b: number; a: number }> = [];
+  
+  for (let y = 0; y < cornerSize; y++) {
+    for (let x = 0; x < cornerSize; x++) {
+      const idx = (width * y + x) * 4;
+      cornerPixels.push({
+        r: png.data[idx],
+        g: png.data[idx + 1],
+        b: png.data[idx + 2],
+        a: png.data[idx + 3],
+      });
+    }
+  }
+  
+  // Calculate average corner color
+  const sum = cornerPixels.reduce(
+    (acc, p) => ({
+      r: acc.r + p.r,
+      g: acc.g + p.g,
+      b: acc.b + p.b,
+      a: acc.a + p.a,
+    }),
+    { r: 0, g: 0, b: 0, a: 0 }
+  );
+  
+  const count = cornerPixels.length;
+  const avgCornerColor = {
+    r: Math.round(sum.r / count),
+    g: Math.round(sum.g / count),
+    b: Math.round(sum.b / count),
+    a: Math.round(sum.a / count),
+  };
+  
+  // Check if corners have uniform color (grey, white, or black)
+  const isGrey = Math.abs(avgCornerColor.r - avgCornerColor.g) < 10 && 
+                 Math.abs(avgCornerColor.g - avgCornerColor.b) < 10;
+  const isDark = avgCornerColor.r < 50 && avgCornerColor.g < 50 && avgCornerColor.b < 50;
+  const isLight = avgCornerColor.r > 180 && avgCornerColor.g > 180 && avgCornerColor.b > 180;
+  
+  return {
+    hasUniformBorder: isGrey && (isDark || isLight),
+    avgCornerColor,
+    isDarkBorder: isGrey && isDark,
+    isLightBorder: isGrey && isLight,
+  };
+}
+
+/**
+ * Find content bounds by analyzing pixel patterns
+ * Detects and excludes:
+ * - Dark bars (black backgrounds)
+ * - Light grey/white borders
+ * - Transparent padding
+ */
+async function findContentBounds(buffer: Buffer): Promise<ContentBounds | null> {
+  const png = PNG.sync.read(buffer);
+  const { width, height } = png;
+  
+  // Track which rows and columns have meaningful content
+  const rowHasContent = new Array(height).fill(false);
+  const colHasContent = new Array(width).fill(false);
+  
+  // Analyze each row
+  for (let y = 0; y < height; y++) {
+    let contentPixels = 0;
+    
+    for (let x = 0; x < width; x++) {
+      const idx = (width * y + x) * 4;
+      const r = png.data[idx];
+      const g = png.data[idx + 1];
+      const b = png.data[idx + 2];
+      const alpha = png.data[idx + 3];
+      
+      // Pixel is "content" if it's not a presentation artifact
+      const isDarkBar = r < 30 && g < 30 && b < 30;
+      const isLightGreyBorder = r > 180 && g > 180 && b > 180 && 
+                                Math.abs(r - g) < 5 && Math.abs(g - b) < 5;
+      const isTransparent = alpha < 10;
+      
+      if (!isDarkBar && !isLightGreyBorder && !isTransparent) {
+        contentPixels++;
+      }
+    }
+    
+    // Row has content if more than 10% of pixels are content
+    if (contentPixels > width * 0.1) {
+      rowHasContent[y] = true;
+    }
+  }
+  
+  // Analyze each column
+  for (let x = 0; x < width; x++) {
+    let contentPixels = 0;
+    
+    for (let y = 0; y < height; y++) {
+      const idx = (width * y + x) * 4;
+      const r = png.data[idx];
+      const g = png.data[idx + 1];
+      const b = png.data[idx + 2];
+      const alpha = png.data[idx + 3];
+      
+      const isDarkBar = r < 30 && g < 30 && b < 30;
+      const isLightGreyBorder = r > 180 && g > 180 && b > 180 && 
+                                Math.abs(r - g) < 5 && Math.abs(g - b) < 5;
+      const isTransparent = alpha < 10;
+      
+      if (!isDarkBar && !isLightGreyBorder && !isTransparent) {
+        contentPixels++;
+      }
+    }
+    
+    if (contentPixels > height * 0.1) {
+      colHasContent[x] = true;
+    }
+  }
+  
+  // Find bounding box
+  const minY = rowHasContent.indexOf(true);
+  const maxY = rowHasContent.lastIndexOf(true);
+  const minX = colHasContent.indexOf(true);
+  const maxX = colHasContent.lastIndexOf(true);
+  
+  if (minY === -1 || minX === -1) {
+    return null; // Could not detect content
+  }
+  
+  return {
+    left: minX,
+    top: minY,
+    width: maxX - minX + 1,
+    height: maxY - minY + 1,
+  };
+}
+
+/**
+ * Apply trim strategy using Sharp's built-in trim
+ */
+async function applyTrimStrategy(
+  buffer: Buffer,
+  threshold: number
+): Promise<{ buffer: Buffer; removed: { top: number; bottom: number; left: number; right: number } }> {
+  const originalMeta = await sharp(buffer).metadata();
+  
+  const result = await sharp(buffer)
+    .trim({ threshold })
+    .toBuffer({ resolveWithObject: true });
+  
+  return {
+    buffer: result.data,
+    removed: {
+      top: 0, // Sharp doesn't expose exact trim amounts
+      bottom: 0,
+      left: 0,
+      right: 0,
+    },
+  };
+}
+
+/**
+ * Apply alpha channel cropping
+ */
+async function applyAlphaCrop(buffer: Buffer): Promise<{ buffer: Buffer; bounds: ContentBounds } | null> {
+  const png = PNG.sync.read(buffer);
+  const { width, height } = png;
+  
+  let minX = width, minY = height, maxX = 0, maxY = 0;
+  const alphaThreshold = 10;
+  
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const idx = (width * y + x) * 4;
+      const alpha = png.data[idx + 3];
+      
+      if (alpha > alphaThreshold) {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+      }
+    }
+  }
+  
+  const bounds = {
+    left: minX,
+    top: minY,
+    width: maxX - minX + 1,
+    height: maxY - minY + 1,
+  };
+  
+  // Only crop if we found meaningful bounds
+  if (bounds.width < 10 || bounds.height < 10 || 
+      bounds.width === width || bounds.height === height) {
+    return null;
+  }
+  
+  const cropped = await sharp(buffer)
+    .extract(bounds)
+    .toBuffer();
+  
+  return { buffer: cropped, bounds };
+}
+
+/**
+ * Apply content-based detection and cropping
+ */
+async function applyContentCrop(
+  buffer: Buffer,
+  aggressiveTrim: boolean
+): Promise<{ buffer: Buffer; bounds: ContentBounds } | null> {
+  const bounds = await findContentBounds(buffer);
+  
+  if (!bounds || bounds.width < 50 || bounds.height < 50) {
+    return null; // Invalid or too small
+  }
+  
+  let processed = await sharp(buffer)
+    .extract(bounds)
+    .toBuffer();
+  
+  // Apply additional trim to clean up edges
+  if (aggressiveTrim) {
+    try {
+      const trimmed = await sharp(processed)
+        .trim({ threshold: 15 })
+        .toBuffer({ resolveWithObject: true });
+      
+      processed = trimmed.data;
+    } catch {
+      // Trim failed, use extracted version
+    }
+  }
+  
+  return { buffer: processed, bounds };
+}
+
+/**
+ * Main preprocessing function - automatically detects and removes Figma artifacts
+ */
+export async function preprocessImage(
+  buffer: Buffer,
+  options: PreprocessOptions = {}
+): Promise<PreprocessResult> {
+  const {
+    strategy = "auto",
+    trimThreshold = 10,
+    aggressiveTrim = true,
+    debug = false,
+  } = options;
+  
+  const originalMeta = await sharp(buffer).metadata();
+  const originalDimensions = {
+    width: originalMeta.width!,
+    height: originalMeta.height!,
+  };
+  
+  const artifactsRemoved: string[] = [];
+  let processedBuffer = buffer;
+  let appliedStrategy: string = strategy;
+  let cropInfo: ContentBounds = {
+    left: 0,
+    top: 0,
+    width: originalDimensions.width,
+    height: originalDimensions.height,
+  };
+  
+  // Strategy: none - return original
+  if (strategy === "none") {
+    return {
+      buffer,
+      appliedStrategy: "none",
+      artifactsRemoved: [],
+      originalDimensions,
+      finalDimensions: originalDimensions,
+      cropInfo,
+    };
+  }
+  
+  // Strategy: trim - use Sharp's built-in trim
+  if (strategy === "trim") {
+    const trimResult = await applyTrimStrategy(buffer, trimThreshold);
+    processedBuffer = trimResult.buffer;
+    artifactsRemoved.push("uniform-borders");
+    appliedStrategy = "trim";
+  }
+  
+  // Strategy: alpha - crop to alpha channel bounds
+  else if (strategy === "alpha") {
+    const alphaResult = await applyAlphaCrop(buffer);
+    if (alphaResult) {
+      processedBuffer = alphaResult.buffer;
+      cropInfo = alphaResult.bounds;
+      artifactsRemoved.push("transparent-padding");
+      appliedStrategy = "alpha";
+    } else {
+      appliedStrategy = "alpha-failed-fallback-none";
+    }
+  }
+  
+  // Strategy: content - detect content bounds
+  else if (strategy === "content") {
+    const contentResult = await applyContentCrop(buffer, aggressiveTrim);
+    if (contentResult) {
+      processedBuffer = contentResult.buffer;
+      cropInfo = contentResult.bounds;
+      artifactsRemoved.push("presentation-artifacts");
+      appliedStrategy = "content";
+    } else {
+      appliedStrategy = "content-failed-fallback-none";
+    }
+  }
+  
+  // Strategy: auto - try strategies in order
+  else if (strategy === "auto") {
+    const edgeAnalysis = await analyzeEdges(buffer);
+    
+    if (debug) {
+      console.log("[preprocess] Edge analysis:", edgeAnalysis);
+    }
+    
+    // Try content detection first (most comprehensive)
+    const contentResult = await applyContentCrop(buffer, aggressiveTrim);
+    if (contentResult) {
+      processedBuffer = contentResult.buffer;
+      cropInfo = contentResult.bounds;
+      
+      if (edgeAnalysis.isDarkBorder) {
+        artifactsRemoved.push("dark-bars");
+      }
+      if (edgeAnalysis.isLightBorder) {
+        artifactsRemoved.push("light-borders");
+      }
+      if (!edgeAnalysis.hasUniformBorder) {
+        artifactsRemoved.push("presentation-artifacts");
+      }
+      
+      appliedStrategy = "auto-content";
+    } else {
+      // Fallback to trim
+      const trimResult = await applyTrimStrategy(buffer, trimThreshold);
+      processedBuffer = trimResult.buffer;
+      artifactsRemoved.push("uniform-borders");
+      appliedStrategy = "auto-trim";
+    }
+  }
+  
+  const finalMeta = await sharp(processedBuffer).metadata();
+  const finalDimensions = {
+    width: finalMeta.width!,
+    height: finalMeta.height!,
+  };
+  
+  if (debug) {
+    console.log("[preprocess] Result:", {
+      appliedStrategy,
+      artifactsRemoved,
+      originalDimensions,
+      finalDimensions,
+      cropInfo,
+    });
+  }
+  
+  return {
+    buffer: processedBuffer,
+    appliedStrategy,
+    artifactsRemoved,
+    originalDimensions,
+    finalDimensions,
+    cropInfo,
+  };
+}

package/src/utils/retry.ts

@@ -0,0 +1,51 @@
+/**
+ * Generic retry utility for wrapping flaky operations.
+ * Supports fixed delay and exponential backoff.
+ */
+
+export interface RetryOptions {
+  /** Maximum number of attempts (default: 2) */
+  maxAttempts?: number;
+  /** Delay between retries in ms (default: 500) */
+  delayMs?: number;
+  /** Use exponential backoff (default: false) */
+  backoff?: boolean;
+  /** Called on each retry with the attempt number and error */
+  onRetry?: (attempt: number, error: Error) => void;
+}
+
+/**
+ * Retry an async function up to `maxAttempts` times.
+ * On failure, waits `delayMs` (optionally with exponential backoff) before retrying.
+ * Throws the last error if all attempts fail.
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {}
+): Promise<T> {
+  const {
+    maxAttempts = 2,
+    delayMs = 500,
+    backoff = false,
+    onRetry,
+  } = options;
+
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error: any) {
+      lastError = error;
+      if (attempt < maxAttempts) {
+        onRetry?.(attempt, error);
+        const waitMs = backoff
+          ? delayMs * Math.pow(2, attempt - 1)
+          : delayMs;
+        await new Promise((r) => setTimeout(r, waitMs));
+      }
+    }
+  }
+
+  throw lastError;
+}

package/src/visual/comparator.ts

@@ -0,0 +1,191 @@
+import { writeFile } from "fs/promises";
+import { PNG } from "pngjs";
+import pixelmatch from "pixelmatch";
+import { preprocessImage, type PreprocessOptions } from "../utils/image-preprocess.js";
+
+/**
+ * Visual comparison engine — compares screenshots against reference images
+ * using pixel-level diffing. Returns a similarity score and a diff image.
+ */
+
+export interface ComparisonResult {
+  /** Similarity score between 0.0 (completely different) and 1.0 (identical) */
+  similarity: number;
+  /** Number of different pixels */
+  diffPixels: number;
+  /** Total pixels compared */
+  totalPixels: number;
+  /** Path to the diff image (red = differences) */
+  diffImagePath: string;
+  /** Human-readable summary */
+  summary: string;
+}
+
+export interface PreprocessConfig {
+  /** Whether to enable preprocessing */
+  enabled: boolean;
+  /** Strategy to use for artifact removal */
+  strategy?: "auto" | "trim" | "alpha" | "content" | "none";
+  /** Threshold for trim strategy (0-255) */
+  trimThreshold?: number;
+  /** Apply aggressive trimming after content detection */
+  aggressiveTrim?: boolean;
+  /** Save preprocessed image for debugging */
+  saveDebugImage?: boolean;
+}
+
+export interface ComparisonOptions {
+  /** Color difference threshold (0-1). Lower = stricter. Default: 0.1 */
+  threshold?: number;
+  /**
+   * How to handle dimension mismatches:
+   * - "fit" (default): resize both to the smaller dimensions
+   * - "scale": resize smaller image up to the larger dimensions
+   * - "crop": extract the overlapping region from both
+   */
+  resizeStrategy?: "fit" | "scale" | "crop";
+  /**
+   * Preprocess reference image to remove Figma artifacts.
+   * Can be boolean (use defaults) or config object for fine control.
+   * Defaults to false for backward compatibility.
+   */
+  preprocessReference?: boolean | PreprocessConfig;
+}
+
+/**
+ * Compare a screenshot buffer against a reference image buffer.
+ * Both images are resized/cropped to match dimensions before comparison.
+ */
+export async function compareScreenshots(
+  screenshotBuffer: Buffer,
+  referenceBuffer: Buffer,
+  options: ComparisonOptions = {}
+): Promise<ComparisonResult> {
+  const { threshold = 0.1, resizeStrategy = "fit", preprocessReference } = options;
+
+  // Preprocess reference image if requested
+  let processedReferenceBuffer = referenceBuffer;
+  if (preprocessReference) {
+    const preprocessConfig: PreprocessOptions = 
+      typeof preprocessReference === "boolean"
+        ? { strategy: "auto" }
+        : {
+            strategy: preprocessReference.strategy,
+            trimThreshold: preprocessReference.trimThreshold,
+            aggressiveTrim: preprocessReference.aggressiveTrim,
+          };
+    
+    const preprocessResult = await preprocessImage(referenceBuffer, preprocessConfig);
+    processedReferenceBuffer = preprocessResult.buffer;
+    
+    // Save debug image if requested
+    if (typeof preprocessReference === "object" && preprocessReference.saveDebugImage) {
+      const debugPath = `/tmp/devlens-preprocessed-${Date.now()}.png`;
+      await writeFile(debugPath, processedReferenceBuffer);
+      console.log(`[comparator] Preprocessed reference saved to: ${debugPath}`);
+      console.log(`[comparator] Removed artifacts: ${preprocessResult.artifactsRemoved.join(", ") || "none"}`);
+      console.log(`[comparator] Strategy used: ${preprocessResult.appliedStrategy}`);
+    }
+  }
+
+  // Decode both PNGs
+  const screenshot = PNG.sync.read(screenshotBuffer);
+  const reference = PNG.sync.read(processedReferenceBuffer);
+
+  // Resize if dimensions don't match
+  let img1 = screenshot;
+  let img2 = reference;
+
+  if (
+    screenshot.width !== reference.width ||
+    screenshot.height !== reference.height
+  ) {
+    const sharp = (await import("sharp")).default;
+
+    if (resizeStrategy === "crop") {
+      // Extract the overlapping region from both images
+      const targetWidth = Math.min(screenshot.width, reference.width);
+      const targetHeight = Math.min(screenshot.height, reference.height);
+
+      const cropped1 = await sharp(screenshotBuffer)
+        .extract({ left: 0, top: 0, width: targetWidth, height: targetHeight })
+        .png()
+        .toBuffer();
+      const cropped2 = await sharp(processedReferenceBuffer)
+        .extract({ left: 0, top: 0, width: targetWidth, height: targetHeight })
+        .png()
+        .toBuffer();
+
+      img1 = PNG.sync.read(cropped1);
+      img2 = PNG.sync.read(cropped2);
+    } else {
+      // "fit" = resize to smaller dimensions, "scale" = resize to larger
+      const targetWidth =
+        resizeStrategy === "scale"
+          ? Math.max(screenshot.width, reference.width)
+          : Math.min(screenshot.width, reference.width);
+      const targetHeight =
+        resizeStrategy === "scale"
+          ? Math.max(screenshot.height, reference.height)
+          : Math.min(screenshot.height, reference.height);
+
+      const resized1 = await sharp(screenshotBuffer)
+        .resize(targetWidth, targetHeight, { fit: "fill" })
+        .png()
+        .toBuffer();
+      const resized2 = await sharp(processedReferenceBuffer)
+        .resize(targetWidth, targetHeight, { fit: "fill" })
+        .png()
+        .toBuffer();
+
+      img1 = PNG.sync.read(resized1);
+      img2 = PNG.sync.read(resized2);
+    }
+  }
+
+  // Create diff image
+  const { width, height } = img1;
+  const diff = new PNG({ width, height });
+
+  // Run pixel comparison
+  const diffPixels = pixelmatch(
+    img1.data,
+    img2.data,
+    diff.data,
+    width,
+    height,
+    {
+      threshold,
+      includeAA: false, // Ignore anti-aliasing differences
+    }
+  );
+
+  const totalPixels = width * height;
+  const similarity = 1 - diffPixels / totalPixels;
+
+  // Save diff image
+  const diffImagePath = `/tmp/devlens-diff-${Date.now()}.png`;
+  const diffBuffer = PNG.sync.write(diff);
+  await writeFile(diffImagePath, diffBuffer);
+
+  // Generate summary
+  const percentage = (similarity * 100).toFixed(1);
+  let summary: string;
+  if (similarity >= 0.95) {
+    summary = `Excellent match (${percentage}%). The implementation closely matches the design.`;
+  } else if (similarity >= 0.85) {
+    summary = `Good match (${percentage}%). Minor differences detected — check spacing, colors, or small layout shifts.`;
+  } else if (similarity >= 0.7) {
+    summary = `Partial match (${percentage}%). Noticeable differences — review the diff image for layout or styling issues.`;
+  } else {
+    summary = `Low match (${percentage}%). Significant differences — the layout may need substantial changes.`;
+  }
+
+  return {
+    similarity,
+    diffPixels,
+    totalPixels,
+    diffImagePath,
+    summary,
+  };
+}