@rankcli/agent-runtime 0.0.15 → 0.0.17

package/src/audit/checks/responsive-images.ts

@@ -1,396 +0,0 @@
-// Responsive Images Check - Essential for Core Web Vitals
-// Reference: "Technical SEO for Developers - 17 Tips to Rank Higher"
-// "Make sure your images are responsive for their screen size"
-// "You should always, always, always lazy load off screen images"
-// "Make sure you're setting height and width on your images" (for CLS)
-
-import * as cheerio from 'cheerio';
-import type { AuditIssue } from '../types.js';
-
-export interface ImageAnalysis {
-  src: string;
-  alt: string | null;
-  width: string | null;
-  height: string | null;
-  loading: 'lazy' | 'eager' | null;
-  decoding: 'async' | 'sync' | 'auto' | null;
-  srcset: string | null;
-  sizes: string | null;
-  isAboveFold: boolean; // Estimated based on position
-  hasExplicitDimensions: boolean;
-  hasResponsiveSrcset: boolean;
-  usesModernFormat: boolean;
-  issues: string[];
-}
-
-export interface ResponsiveImageData {
-  totalImages: number;
-  imagesWithoutDimensions: number;
-  imagesWithoutLazyLoad: number;
-  imagesWithoutSrcset: number;
-  imagesWithoutAlt: number;
-  modernFormatCount: number;
-  legacyFormatCount: number;
-  images: ImageAnalysis[];
-  recommendations: string[];
-}
-
-// Modern image formats
-const MODERN_FORMATS = ['.webp', '.avif'];
-const LEGACY_FORMATS = ['.jpg', '.jpeg', '.png', '.gif', '.bmp'];
-
-/**
- * Analyze individual image element
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function analyzeImage($: cheerio.CheerioAPI, img: any, index: number): ImageAnalysis {
-  const $img = $(img);
-  const issues: string[] = [];
-
-  const src = $img.attr('src') || $img.attr('data-src') || '';
-  const alt = $img.attr('alt');
-  const width = $img.attr('width');
-  const height = $img.attr('height');
-  const loading = $img.attr('loading') as 'lazy' | 'eager' | null;
-  const decoding = $img.attr('decoding') as 'async' | 'sync' | 'auto' | null;
-  const srcset = $img.attr('srcset');
-  const sizes = $img.attr('sizes');
-
-  // Check for explicit dimensions
-  const hasExplicitDimensions = !!(
-    (width && height) ||
-    $img.css('width') ||
-    $img.css('height') ||
-    $img.attr('style')?.includes('width') ||
-    $img.attr('style')?.includes('height')
-  );
-
-  // Check for responsive srcset
-  const hasResponsiveSrcset = !!(srcset && srcset.includes('w'));
-
-  // Check for modern format
-  const srcLower = src.toLowerCase();
-  const usesModernFormat = MODERN_FORMATS.some(fmt => srcLower.includes(fmt));
-
-  // Estimate if above fold (very rough - based on element order)
-  // Images in first 3 <img> tags or in header/hero are likely above fold
-  const isInHeader = $img.closest('header, [class*="hero"], [class*="banner"], [class*="jumbotron"]').length > 0;
-  const isAboveFold = index < 3 || isInHeader;
-
-  // Generate issues
-  if (!hasExplicitDimensions) {
-    issues.push('Missing width/height attributes (causes CLS)');
-  }
-
-  if (alt === undefined || alt === null) {
-    issues.push('Missing alt attribute');
-  } else if (alt === '') {
-    // Empty alt is okay for decorative images but should be noted
-  }
-
-  if (!isAboveFold && loading !== 'lazy') {
-    issues.push('Below-fold image without lazy loading');
-  }
-
-  if (isAboveFold && loading === 'lazy') {
-    issues.push('Above-fold image with lazy loading (delays LCP)');
-  }
-
-  if (!hasResponsiveSrcset && src && !srcLower.includes('.svg')) {
-    issues.push('No responsive srcset for different screen sizes');
-  }
-
-  if (srcset && !sizes) {
-    issues.push('Has srcset but missing sizes attribute');
-  }
-
-  if (!usesModernFormat && src && !srcLower.includes('.svg')) {
-    issues.push('Using legacy image format instead of WebP/AVIF');
-  }
-
-  return {
-    src,
-    alt: alt ?? null,
-    width: width ?? null,
-    height: height ?? null,
-    loading: loading ?? null,
-    decoding: decoding ?? null,
-    srcset: srcset ?? null,
-    sizes: sizes ?? null,
-    isAboveFold,
-    hasExplicitDimensions,
-    hasResponsiveSrcset,
-    usesModernFormat,
-    issues,
-  };
-}
-
-/**
- * Analyze <picture> elements for responsive patterns
- */
-export function analyzePictureElements($: cheerio.CheerioAPI): {
-  hasPictureElements: boolean;
-  pictureCount: number;
-  hasFormatFallbacks: boolean;
-} {
-  const pictures = $('picture');
-  const pictureCount = pictures.length;
-  let hasFormatFallbacks = false;
-
-  pictures.each((_, pic) => {
-    const sources = $(pic).find('source');
-    const hasWebP = sources.filter((_, s) => {
-      const type = $(s).attr('type') || '';
-      const srcset = $(s).attr('srcset') || '';
-      return type.includes('webp') || srcset.includes('.webp');
-    }).length > 0;
-    const hasAvif = sources.filter((_, s) => {
-      const type = $(s).attr('type') || '';
-      const srcset = $(s).attr('srcset') || '';
-      return type.includes('avif') || srcset.includes('.avif');
-    }).length > 0;
-
-    if (hasWebP || hasAvif) {
-      hasFormatFallbacks = true;
-    }
-  });
-
-  return {
-    hasPictureElements: pictureCount > 0,
-    pictureCount,
-    hasFormatFallbacks,
-  };
-}
-
-/**
- * Check for image CDN usage
- */
-export function detectImageCDN(html: string): { detected: boolean; cdns: string[] } {
-  const cdnPatterns = [
-    { name: 'Cloudinary', pattern: /cloudinary\.com|res\.cloudinary/i },
-    { name: 'imgix', pattern: /imgix\.net/i },
-    { name: 'Cloudflare Images', pattern: /imagedelivery\.net|cloudflare-images/i },
-    { name: 'AWS CloudFront', pattern: /cloudfront\.net/i },
-    { name: 'Fastly', pattern: /fastly\.net/i },
-    { name: 'ImageKit', pattern: /imagekit\.io|ik\.imagekit/i },
-    { name: 'Vercel Image Optimization', pattern: /_next\/image/i },
-    { name: 'Prismic', pattern: /images\.prismic\.io/i },
-    { name: 'Contentful', pattern: /images\.ctfassets\.net/i },
-    { name: 'Sanity', pattern: /cdn\.sanity\.io/i },
-    { name: 'Shopify CDN', pattern: /cdn\.shopify\.com/i },
-    { name: 'WordPress Jetpack', pattern: /i\d\.wp\.com/i },
-  ];
-
-  const detectedCDNs: string[] = [];
-
-  for (const { name, pattern } of cdnPatterns) {
-    if (pattern.test(html)) {
-      detectedCDNs.push(name);
-    }
-  }
-
-  return {
-    detected: detectedCDNs.length > 0,
-    cdns: detectedCDNs,
-  };
-}
-
-/**
- * Main function: Analyze responsive image best practices
- */
-export function analyzeResponsiveImages(
-  html: string,
-  url: string
-): { issues: AuditIssue[]; data: ResponsiveImageData } {
-  const $ = cheerio.load(html);
-  const issues: AuditIssue[] = [];
-  const images: ImageAnalysis[] = [];
-
-  // Analyze all images
-  const imgElements = $('img');
-  imgElements.each((index, img) => {
-    const analysis = analyzeImage($, img, index);
-    images.push(analysis);
-  });
-
-  // Analyze picture elements
-  const pictureData = analyzePictureElements($);
-
-  // Detect image CDN usage
-  const cdnData = detectImageCDN(html);
-
-  // Calculate statistics
-  const totalImages = images.length;
-  const imagesWithoutDimensions = images.filter(i => !i.hasExplicitDimensions).length;
-  const imagesWithoutLazyLoad = images.filter(i => !i.isAboveFold && i.loading !== 'lazy').length;
-  const imagesWithoutSrcset = images.filter(i => !i.hasResponsiveSrcset && i.src && !i.src.includes('.svg')).length;
-  const imagesWithoutAlt = images.filter(i => i.alt === null).length;
-  const modernFormatCount = images.filter(i => i.usesModernFormat).length;
-  const legacyFormatCount = images.filter(i =>
-    !i.usesModernFormat && i.src && !i.src.includes('.svg')
-  ).length;
-
-  // Generate recommendations
-  const recommendations: string[] = [];
-
-  if (!cdnData.detected && totalImages > 3) {
-    recommendations.push('Consider using an image CDN (Cloudinary, imgix, Vercel) for automatic optimization');
-  }
-
-  if (!pictureData.hasPictureElements && legacyFormatCount > 0) {
-    recommendations.push('Use <picture> elements with WebP/AVIF sources and JPEG/PNG fallbacks');
-  }
-
-  if (imagesWithoutDimensions > 0) {
-    recommendations.push('Add width and height attributes to all images to prevent layout shift');
-  }
-
-  if (imagesWithoutLazyLoad > 0) {
-    recommendations.push('Add loading="lazy" to below-fold images');
-  }
-
-  if (imagesWithoutSrcset > 0) {
-    recommendations.push('Add srcset with multiple sizes for responsive images');
-  }
-
-  // Generate issues
-
-  // Critical: Many images without dimensions (CLS impact)
-  if (imagesWithoutDimensions >= 3) {
-    issues.push({
-      code: 'IMAGES_MISSING_DIMENSIONS',
-      severity: 'error',
-      category: 'performance',
-      title: `${imagesWithoutDimensions} images missing width/height attributes`,
-      description: `Found ${imagesWithoutDimensions} images without explicit dimensions.`,
-      impact: 'Missing dimensions cause Cumulative Layout Shift (CLS) when images load.',
-      howToFix: 'Add width and height attributes to all <img> tags, even with CSS sizing.',
-      affectedUrls: [url],
-      details: {
-        count: imagesWithoutDimensions,
-        images: images.filter(i => !i.hasExplicitDimensions).slice(0, 5).map(i => i.src),
-      },
-    });
-  } else if (imagesWithoutDimensions > 0) {
-    issues.push({
-      code: 'IMAGES_MISSING_DIMENSIONS',
-      severity: 'warning',
-      category: 'performance',
-      title: `${imagesWithoutDimensions} image(s) missing width/height attributes`,
-      description: `Found ${imagesWithoutDimensions} images without explicit dimensions.`,
-      impact: 'Missing dimensions cause Cumulative Layout Shift (CLS) when images load.',
-      howToFix: 'Add width and height attributes to all <img> tags.',
-      affectedUrls: [url],
-      details: {
-        images: images.filter(i => !i.hasExplicitDimensions).map(i => i.src),
-      },
-    });
-  }
-
-  // Warning: Images without lazy loading
-  if (imagesWithoutLazyLoad >= 3) {
-    issues.push({
-      code: 'IMAGES_WITHOUT_LAZY_LOAD',
-      severity: 'warning',
-      category: 'performance',
-      title: `${imagesWithoutLazyLoad} below-fold images without lazy loading`,
-      description: `Found ${imagesWithoutLazyLoad} images below the fold that load immediately.`,
-      impact: 'Eager-loading all images delays initial page load and wastes bandwidth.',
-      howToFix: 'Add loading="lazy" to images below the fold. Keep loading="eager" for hero images.',
-      affectedUrls: [url],
-      details: {
-        count: imagesWithoutLazyLoad,
-        images: images.filter(i => !i.isAboveFold && i.loading !== 'lazy').slice(0, 5).map(i => i.src),
-      },
-    });
-  }
-
-  // Warning: No responsive images
-  if (imagesWithoutSrcset >= 5 && totalImages >= 5) {
-    issues.push({
-      code: 'NO_RESPONSIVE_IMAGES',
-      severity: 'warning',
-      category: 'performance',
-      title: 'Images lack responsive srcset',
-      description: `${imagesWithoutSrcset} of ${totalImages} images don't have srcset for different screen sizes.`,
-      impact: 'Mobile users download full-size images, wasting bandwidth and slowing load.',
-      howToFix: 'Add srcset attribute with multiple image sizes (e.g., 320w, 640w, 1280w).',
-      affectedUrls: [url],
-      details: {
-        withoutSrcset: imagesWithoutSrcset,
-        total: totalImages,
-      },
-    });
-  }
-
-  // Warning: Missing alt text
-  if (imagesWithoutAlt > 0) {
-    issues.push({
-      code: 'IMAGES_MISSING_ALT',
-      severity: 'warning',
-      category: 'on-page', // Alt text impacts both accessibility and SEO
-      title: `${imagesWithoutAlt} image(s) missing alt attribute`,
-      description: `Found ${imagesWithoutAlt} images without alt text.`,
-      impact: 'Missing alt text hurts accessibility and SEO. Screen readers cannot describe the image.',
-      howToFix: 'Add descriptive alt text to all images. Use alt="" only for purely decorative images.',
-      affectedUrls: [url],
-      details: {
-        count: imagesWithoutAlt,
-        images: images.filter(i => i.alt === null).slice(0, 5).map(i => i.src),
-      },
-    });
-  }
-
-  // Notice: Not using modern formats
-  if (legacyFormatCount > 3 && modernFormatCount === 0 && !pictureData.hasFormatFallbacks) {
-    issues.push({
-      code: 'NO_MODERN_IMAGE_FORMATS',
-      severity: 'notice',
-      category: 'performance',
-      title: 'Not using modern image formats (WebP/AVIF)',
-      description: `All ${legacyFormatCount} images use legacy formats (JPEG/PNG) instead of WebP/AVIF.`,
-      impact: 'WebP is 25-35% smaller than JPEG. AVIF is up to 50% smaller.',
-      howToFix: 'Use <picture> element to serve WebP/AVIF with JPEG fallback, or use an image CDN.',
-      affectedUrls: [url],
-      details: {
-        legacyCount: legacyFormatCount,
-        suggestion: cdnData.detected
-          ? `Your CDN (${cdnData.cdns.join(', ')}) likely supports format conversion.`
-          : 'Consider using Cloudinary, imgix, or Vercel Image Optimization.',
-      },
-    });
-  }
-
-  // Notice: Above-fold images with lazy loading
-  const aboveFoldLazy = images.filter(i => i.isAboveFold && i.loading === 'lazy');
-  if (aboveFoldLazy.length > 0) {
-    issues.push({
-      code: 'HERO_IMAGE_LAZY',
-      severity: 'notice',
-      category: 'performance',
-      title: 'Above-fold images have lazy loading',
-      description: `${aboveFoldLazy.length} hero/above-fold image(s) use loading="lazy" which delays LCP.`,
-      impact: 'Lazy loading above-fold images increases Largest Contentful Paint time.',
-      howToFix: 'Remove loading="lazy" from images visible on initial page load.',
-      affectedUrls: [url],
-      details: {
-        images: aboveFoldLazy.map(i => i.src),
-      },
-    });
-  }
-
-  return {
-    issues,
-    data: {
-      totalImages,
-      imagesWithoutDimensions,
-      imagesWithoutLazyLoad,
-      imagesWithoutSrcset,
-      imagesWithoutAlt,
-      modernFormatCount,
-      legacyFormatCount,
-      images,
-      recommendations,
-    },
-  };
-}