@rankcli/agent-runtime 0.0.15 → 0.0.16

package/src/audit/checks/resource-hints.ts

@@ -1,420 +0,0 @@
-// Resource Hints Optimization Checks
-// Analyzes dns-prefetch, preconnect, prefetch, preload, modulepreload, and early hints
-// Based on advanced performance SEO research
-
-import * as cheerio from 'cheerio';
-import { httpGet } from '../../utils/http.js';
-import type { AuditIssue } from '../types.js';
-
-export interface ResourceHint {
-  type: 'dns-prefetch' | 'preconnect' | 'prefetch' | 'preload' | 'modulepreload';
-  href: string;
-  as?: string;
-  crossorigin?: string;
-}
-
-export interface ResourceHintsData {
-  dnsPrefetch: string[];
-  preconnect: string[];
-  prefetch: string[];
-  preload: ResourceHint[];
-  modulepreload: string[];
-  thirdPartyDomains: string[];
-  missingPreconnects: string[];
-  earlyHints: boolean;
-  http2Push: boolean;
-}
-
-/**
- * Extract all resource hints from HTML
- */
-export function extractResourceHints(html: string): ResourceHint[] {
-  const $ = cheerio.load(html);
-  const hints: ResourceHint[] = [];
-
-  // dns-prefetch
-  $('link[rel="dns-prefetch"]').each((_, el) => {
-    const href = $(el).attr('href');
-    if (href) {
-      hints.push({ type: 'dns-prefetch', href });
-    }
-  });
-
-  // preconnect
-  $('link[rel="preconnect"]').each((_, el) => {
-    const href = $(el).attr('href');
-    if (href) {
-      hints.push({
-        type: 'preconnect',
-        href,
-        crossorigin: $(el).attr('crossorigin'),
-      });
-    }
-  });
-
-  // prefetch
-  $('link[rel="prefetch"]').each((_, el) => {
-    const href = $(el).attr('href');
-    if (href) {
-      hints.push({
-        type: 'prefetch',
-        href,
-        as: $(el).attr('as'),
-      });
-    }
-  });
-
-  // preload
-  $('link[rel="preload"]').each((_, el) => {
-    const href = $(el).attr('href');
-    if (href) {
-      hints.push({
-        type: 'preload',
-        href,
-        as: $(el).attr('as'),
-        crossorigin: $(el).attr('crossorigin'),
-      });
-    }
-  });
-
-  // modulepreload
-  $('link[rel="modulepreload"]').each((_, el) => {
-    const href = $(el).attr('href');
-    if (href) {
-      hints.push({ type: 'modulepreload', href });
-    }
-  });
-
-  return hints;
-}
-
-/**
- * Detect third-party domains used on the page
- */
-export function detectThirdPartyDomains(html: string, pageUrl: string): string[] {
-  const $ = cheerio.load(html);
-  const baseDomain = new URL(pageUrl).hostname;
-  const domains = new Set<string>();
-
-  // Check scripts
-  $('script[src]').each((_, el) => {
-    try {
-      const src = $(el).attr('src')!;
-      const url = new URL(src, pageUrl);
-      if (url.hostname !== baseDomain) {
-        domains.add(url.origin);
-      }
-    } catch {
-      // Invalid URL
-    }
-  });
-
-  // Check stylesheets
-  $('link[rel="stylesheet"][href]').each((_, el) => {
-    try {
-      const href = $(el).attr('href')!;
-      const url = new URL(href, pageUrl);
-      if (url.hostname !== baseDomain) {
-        domains.add(url.origin);
-      }
-    } catch {
-      // Invalid URL
-    }
-  });
-
-  // Check images
-  $('img[src]').each((_, el) => {
-    try {
-      const src = $(el).attr('src')!;
-      const url = new URL(src, pageUrl);
-      if (url.hostname !== baseDomain) {
-        domains.add(url.origin);
-      }
-    } catch {
-      // Invalid URL
-    }
-  });
-
-  // Check fonts (from @font-face in style tags - simplified)
-  const styleContent = $('style').text();
-  const fontUrlMatches = styleContent.match(/url\(['"]?(https?:\/\/[^'")\s]+)/g) || [];
-  for (const match of fontUrlMatches) {
-    try {
-      const url = match.replace(/url\(['"]?/, '');
-      const parsed = new URL(url);
-      if (parsed.hostname !== baseDomain) {
-        domains.add(parsed.origin);
-      }
-    } catch {
-      // Invalid URL
-    }
-  }
-
-  return [...domains];
-}
-
-/**
- * Common third-party services that should have preconnect
- */
-const CRITICAL_THIRD_PARTIES: Record<string, string[]> = {
-  'fonts.googleapis.com': ['https://fonts.googleapis.com', 'https://fonts.gstatic.com'],
-  'fonts.gstatic.com': ['https://fonts.googleapis.com', 'https://fonts.gstatic.com'],
-  'www.google-analytics.com': ['https://www.google-analytics.com'],
-  'www.googletagmanager.com': ['https://www.googletagmanager.com'],
-  'cdn.jsdelivr.net': ['https://cdn.jsdelivr.net'],
-  'unpkg.com': ['https://unpkg.com'],
-  'cdnjs.cloudflare.com': ['https://cdnjs.cloudflare.com'],
-  'ajax.googleapis.com': ['https://ajax.googleapis.com'],
-  'connect.facebook.net': ['https://connect.facebook.net'],
-  'platform.twitter.com': ['https://platform.twitter.com'],
-  'www.youtube.com': ['https://www.youtube.com', 'https://i.ytimg.com'],
-  'player.vimeo.com': ['https://player.vimeo.com'],
-  'js.stripe.com': ['https://js.stripe.com'],
-};
-
-/**
- * Find missing preconnects for critical third-party resources
- */
-export function findMissingPreconnects(
-  thirdPartyDomains: string[],
-  existingHints: ResourceHint[]
-): string[] {
-  const preconnected = new Set(
-    existingHints
-      .filter((h) => h.type === 'preconnect' || h.type === 'dns-prefetch')
-      .map((h) => {
-        try {
-          return new URL(h.href).origin;
-        } catch {
-          return h.href;
-        }
-      })
-  );
-
-  const missing: string[] = [];
-
-  for (const domain of thirdPartyDomains) {
-    try {
-      const hostname = new URL(domain).hostname;
-      const recommended = CRITICAL_THIRD_PARTIES[hostname] || [domain];
-
-      for (const rec of recommended) {
-        if (!preconnected.has(rec)) {
-          missing.push(rec);
-        }
-      }
-    } catch {
-      // Invalid URL
-    }
-  }
-
-  return [...new Set(missing)];
-}
-
-/**
- * Check for HTTP/2 Server Push and 103 Early Hints
- */
-export async function checkAdvancedHints(
-  url: string
-): Promise<{ earlyHints: boolean; http2Push: boolean; linkHeaders: string[] }> {
-  try {
-    const response = await httpGet<string>(url, {
-      
-      timeout: 10000,
-      validateStatus: () => true,
-      // Note: fetch doesn't expose HTTP/2 details natively, this is simplified
-    });
-
-    const linkHeader = response.headers['link'] || '';
-    const linkHeaders = Array.isArray(linkHeader) ? linkHeader : [linkHeader];
-
-    // Check for preload hints in Link header
-    const hasPreloadLinks = linkHeaders.some(
-      (h) => h.includes('rel=preload') || h.includes("rel='preload'") || h.includes('rel="preload"')
-    );
-
-    return {
-      earlyHints: false, // Would need special handling to detect 103
-      http2Push: hasPreloadLinks,
-      linkHeaders: linkHeaders.filter(Boolean),
-    };
-  } catch {
-    return { earlyHints: false, http2Push: false, linkHeaders: [] };
-  }
-}
-
-/**
- * Analyze preload usage for critical resources
- */
-export function analyzePreloads(
-  html: string,
-  preloads: ResourceHint[]
-): { missing: string[]; unused: string[] } {
-  const $ = cheerio.load(html);
-  const criticalResources: string[] = [];
-
-  // LCP image candidates (large hero images)
-  $('img').each((i, el) => {
-    if (i === 0) {
-      // First image is often LCP
-      const src = $(el).attr('src');
-      if (src) criticalResources.push(src);
-    }
-  });
-
-  // Critical fonts
-  $('link[rel="stylesheet"][href*="font"]').each((_, el) => {
-    const href = $(el).attr('href');
-    if (href) criticalResources.push(href);
-  });
-
-  // Check for missing preloads
-  const preloadedUrls = new Set(preloads.map((p) => p.href));
-  const missing = criticalResources.filter((r) => !preloadedUrls.has(r));
-
-  // Check for unused preloads (preloaded but not used)
-  // This would need runtime analysis, so we'll do a basic check
-  const pageContent = $.html();
-  const unused = preloads
-    .map((p) => p.href)
-    .filter((href) => !pageContent.includes(href.split('/').pop() || ''));
-
-  return { missing: missing.slice(0, 3), unused };
-}
-
-/**
- * Main function: Analyze resource hints optimization
- */
-export function analyzeResourceHints(
-  html: string,
-  url: string
-): { issues: AuditIssue[]; data: ResourceHintsData } {
-  const issues: AuditIssue[] = [];
-
-  const hints = extractResourceHints(html);
-  const thirdPartyDomains = detectThirdPartyDomains(html, url);
-  const missingPreconnects = findMissingPreconnects(thirdPartyDomains, hints);
-
-  const dnsPrefetch = hints.filter((h) => h.type === 'dns-prefetch').map((h) => h.href);
-  const preconnect = hints.filter((h) => h.type === 'preconnect').map((h) => h.href);
-  const prefetch = hints.filter((h) => h.type === 'prefetch').map((h) => h.href);
-  const preload = hints.filter((h) => h.type === 'preload');
-  const modulepreload = hints.filter((h) => h.type === 'modulepreload').map((h) => h.href);
-
-  // Check for missing preconnects
-  if (missingPreconnects.length > 0) {
-    issues.push({
-      code: 'MISSING_PRECONNECT',
-      severity: 'warning',
-      category: 'performance',
-      title: 'Missing preconnect hints for third-party origins',
-      description: `${missingPreconnects.length} third-party origins used without preconnect hints.`,
-      impact: 'Connection setup to third-party origins adds latency to resource loading.',
-      howToFix: `Add preconnect hints: ${missingPreconnects.slice(0, 3).map((d) => `<link rel="preconnect" href="${d}">`).join(' ')}`,
-      affectedUrls: [url],
-      details: { missingPreconnects: missingPreconnects.slice(0, 5) },
-    });
-  }
-
-  // Check if Google Fonts are used without proper hints
-  const usesGoogleFonts = thirdPartyDomains.some(
-    (d) => d.includes('fonts.googleapis.com') || d.includes('fonts.gstatic.com')
-  );
-  const hasGoogleFontsPreconnect =
-    preconnect.some((h) => h.includes('fonts.googleapis.com')) &&
-    preconnect.some((h) => h.includes('fonts.gstatic.com'));
-
-  if (usesGoogleFonts && !hasGoogleFontsPreconnect) {
-    issues.push({
-      code: 'GOOGLE_FONTS_NO_PRECONNECT',
-      severity: 'warning',
-      category: 'performance',
-      title: 'Google Fonts without preconnect',
-      description: 'Google Fonts are used but preconnect hints are missing.',
-      impact: 'Adds significant latency to font loading, affecting LCP.',
-      howToFix:
-        'Add: <link rel="preconnect" href="https://fonts.googleapis.com"> and <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>',
-      affectedUrls: [url],
-    });
-  }
-
-  // Check for LCP image preload
-  const $ = cheerio.load(html);
-  const hasHeroImage = $('img').first().length > 0;
-  const hasImagePreload = preload.some((p) => p.as === 'image');
-
-  if (hasHeroImage && !hasImagePreload) {
-    issues.push({
-      code: 'HERO_IMAGE_NOT_PRELOADED',
-      severity: 'notice',
-      category: 'performance',
-      title: 'Hero image not preloaded',
-      description: 'Page has images but none are preloaded for faster LCP.',
-      impact: 'Preloading LCP images can improve Largest Contentful Paint.',
-      howToFix: 'Add <link rel="preload" href="hero-image.jpg" as="image"> for your LCP image.',
-      affectedUrls: [url],
-    });
-  }
-
-  // Check for critical CSS preload
-  const hasRenderBlockingCSS =
-    $('link[rel="stylesheet"]').filter((_, el) => !$(el).attr('media') || $(el).attr('media') === 'all').length > 0;
-  const hasCSSPreload = preload.some((p) => p.as === 'style');
-
-  if (hasRenderBlockingCSS && !hasCSSPreload && preload.length === 0) {
-    issues.push({
-      code: 'NO_CRITICAL_RESOURCE_PRELOAD',
-      severity: 'notice',
-      category: 'performance',
-      title: 'No critical resources preloaded',
-      description: 'Page has render-blocking resources but no preload hints.',
-      impact: 'Preloading critical resources can improve initial render time.',
-      howToFix: 'Consider preloading critical CSS, fonts, or hero images.',
-      affectedUrls: [url],
-    });
-  }
-
-  // Check for excessive preloads (can hurt performance)
-  if (preload.length > 10) {
-    issues.push({
-      code: 'EXCESSIVE_PRELOADS',
-      severity: 'warning',
-      category: 'performance',
-      title: 'Too many preload hints',
-      description: `Page has ${preload.length} preload hints, which can degrade performance.`,
-      impact: 'Preloading too many resources competes for bandwidth and can delay critical resources.',
-      howToFix: 'Limit preloads to truly critical resources (2-5 maximum).',
-      affectedUrls: [url],
-    });
-  }
-
-  // Check for modulepreload for ES modules
-  const hasESModules = $('script[type="module"]').length > 0;
-  if (hasESModules && modulepreload.length === 0) {
-    issues.push({
-      code: 'ES_MODULES_NO_MODULEPRELOAD',
-      severity: 'notice',
-      category: 'performance',
-      title: 'ES modules without modulepreload',
-      description: 'Page uses ES modules but no modulepreload hints are present.',
-      impact: 'Modulepreload can parallelize module loading for faster execution.',
-      howToFix: 'Add <link rel="modulepreload" href="critical-module.js"> for critical modules.',
-      affectedUrls: [url],
-    });
-  }
-
-  return {
-    issues,
-    data: {
-      dnsPrefetch,
-      preconnect,
-      prefetch,
-      preload,
-      modulepreload,
-      thirdPartyDomains,
-      missingPreconnects,
-      earlyHints: false,
-      http2Push: false,
-    },
-  };
-}

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

@@ -1,247 +0,0 @@
-/**
- * Responsive CSS Check
- *
- * Checks if the site uses responsive design through CSS media queries.
- * Responsive design is essential for:
- * - Mobile-first indexing (Google uses mobile version for ranking)
- * - User experience across devices
- * - Core Web Vitals on mobile
- *
- * Detection methods:
- * - @media queries in inline styles
- * - @media queries in linked stylesheets
- * - Viewport meta tag (required for responsiveness)
- */
-
-import { httpGet } from '../../utils/http.js';
-import * as cheerio from 'cheerio';
-import type { AuditIssue } from '../types.js';
-
-export interface ResponsiveCssData {
-  hasViewport: boolean;
-  viewportContent?: string;
-  hasMediaQueries: boolean;
-  mediaQueryCount: number;
-  mediaQuerySources: {
-    inline: number;
-    external: string[];
-  };
-  breakpoints: string[];
-  hasMobileBreakpoint: boolean;
-  hasTabletBreakpoint: boolean;
-  hasDesktopBreakpoint: boolean;
-}
-
-/**
- * Extract media queries from CSS content
- */
-function extractMediaQueries(css: string): string[] {
-  const mediaQueries: string[] = [];
-  // Match @media queries
-  const regex = /@media\s*([^{]+)/g;
-  let match;
-  while ((match = regex.exec(css)) !== null) {
-    mediaQueries.push(match[1].trim());
-  }
-  return mediaQueries;
-}
-
-/**
- * Classify breakpoints
- */
-function classifyBreakpoints(mediaQueries: string[]): {
-  hasMobile: boolean;
-  hasTablet: boolean;
-  hasDesktop: boolean;
-  breakpoints: string[];
-} {
-  const breakpoints = new Set<string>();
-  let hasMobile = false;
-  let hasTablet = false;
-  let hasDesktop = false;
-
-  for (const query of mediaQueries) {
-    // Extract width values from media queries
-    const widthMatches = query.match(/(?:min|max)-width\s*:\s*(\d+)(?:px|em|rem)?/gi);
-    if (widthMatches) {
-      for (const match of widthMatches) {
-        const valueMatch = match.match(/(\d+)/);
-        if (valueMatch) {
-          const value = parseInt(valueMatch[1], 10);
-          breakpoints.add(`${value}px`);
-
-          // Classify breakpoint
-          if (value <= 480) {
-            hasMobile = true;
-          } else if (value <= 768) {
-            hasMobile = true; // Small tablet / large phone
-          } else if (value <= 1024) {
-            hasTablet = true;
-          } else {
-            hasDesktop = true;
-          }
-        }
-      }
-    }
-
-    // Check for common responsive patterns
-    if (/screen\s+and/i.test(query)) {
-      // Has screen media type - indicates responsive design
-    }
-
-    // Check for print media (not responsive but valid)
-    if (/print/i.test(query)) {
-      continue; // Don't count print as responsive
-    }
-  }
-
-  return {
-    hasMobile,
-    hasTablet,
-    hasDesktop,
-    breakpoints: Array.from(breakpoints).sort((a, b) => parseInt(a) - parseInt(b)),
-  };
-}
-
-/**
- * Analyze responsive CSS
- */
-export async function analyzeResponsiveCss(
-  html: string,
-  url: string
-): Promise<{ issues: AuditIssue[]; data: ResponsiveCssData }> {
-  const issues: AuditIssue[] = [];
-  const $ = cheerio.load(html);
-  const baseUrl = new URL(url);
-
-  // Check viewport meta tag
-  const viewportMeta = $('meta[name="viewport"]').attr('content');
-  const hasViewport = !!viewportMeta;
-
-  // Collect all media queries
-  const allMediaQueries: string[] = [];
-  const externalSources: string[] = [];
-  let inlineCount = 0;
-
-  // Check inline styles
-  $('style').each((_, el) => {
-    const css = $(el).text();
-    const queries = extractMediaQueries(css);
-    if (queries.length > 0) {
-      allMediaQueries.push(...queries);
-      inlineCount += queries.length;
-    }
-  });
-
-  // Check linked stylesheets (first-party only, limit to 3)
-  const cssLinks = $('link[rel="stylesheet"][href]')
-    .toArray()
-    .slice(0, 3)
-    .map((el) => $(el).attr('href'))
-    .filter((href): href is string => {
-      if (!href || href.startsWith('data:')) return false;
-      try {
-        const cssHostname = new URL(href, url).hostname;
-        return cssHostname === baseUrl.hostname;
-      } catch {
-        return false;
-      }
-    });
-
-  // Fetch CSS files in parallel with short timeout
-  const cssPromises = cssLinks.map(async (cssUrl) => {
-    try {
-      const fullUrl = new URL(cssUrl, url).href;
-      const response = await httpGet<string>(fullUrl, {
-        timeout: 3000, // Reduced timeout
-        validateStatus: () => true,
-      });
-
-      if (response.status === 200 && typeof response.data === 'string') {
-        const queries = extractMediaQueries(response.data);
-        if (queries.length > 0) {
-          allMediaQueries.push(...queries);
-          externalSources.push(cssUrl);
-        }
-      }
-    } catch {
-      // Skip failed requests
-    }
-  });
-
-  // Wait for all CSS checks with overall timeout
-  await Promise.race([
-    Promise.all(cssPromises),
-    new Promise<void>((resolve) => setTimeout(resolve, 6000)), // 6s overall timeout
-  ]);
-
-  const hasMediaQueries = allMediaQueries.length > 0;
-  const { hasMobile, hasTablet, hasDesktop, breakpoints } = classifyBreakpoints(allMediaQueries);
-
-  // Generate issues
-  if (!hasViewport) {
-    issues.push({
-      code: 'RESPONSIVE_NO_VIEWPORT',
-      severity: 'error',
-      category: 'mobile',
-      title: 'Missing viewport meta tag',
-      description: 'No viewport meta tag found. This is required for responsive design to work properly.',
-      impact:
-        'Without a viewport meta tag, mobile browsers will render the page at desktop width and scale down, making it unusable.',
-      howToFix: 'Add <meta name="viewport" content="width=device-width, initial-scale=1"> to the <head> section.',
-      affectedUrls: [url],
-    });
-  }
-
-  if (!hasMediaQueries) {
-    issues.push({
-      code: 'RESPONSIVE_NO_MEDIA_QUERIES',
-      severity: 'warning',
-      category: 'mobile',
-      title: 'No CSS media queries detected',
-      description: 'No @media queries found in inline styles or first-party stylesheets.',
-      impact:
-        'Without media queries, the site likely uses fixed layouts that do not adapt to different screen sizes. This hurts mobile usability and SEO.',
-      howToFix:
-        'Add CSS media queries to adapt layout for different screen sizes. Consider using a mobile-first approach with min-width breakpoints.',
-      affectedUrls: [url],
-      details: {
-        suggestion: 'Common breakpoints: 480px (mobile), 768px (tablet), 1024px (desktop)',
-      },
-    });
-  } else if (!hasMobile && !hasTablet) {
-    issues.push({
-      code: 'RESPONSIVE_NO_MOBILE_BREAKPOINT',
-      severity: 'warning',
-      category: 'mobile',
-      title: 'No mobile breakpoints detected',
-      description: `Found ${allMediaQueries.length} media queries but none target mobile screen sizes (≤768px).`,
-      impact:
-        'Site may not be optimized for mobile devices, which affects majority of web traffic and Google mobile-first indexing.',
-      howToFix:
-        'Add media queries for mobile devices. Example: @media (max-width: 768px) { ... } or use min-width for mobile-first.',
-      affectedUrls: [url],
-      details: {
-        detectedBreakpoints: breakpoints,
-      },
-    });
-  }
-
-  return {
-    issues,
-    data: {
-      hasViewport,
-      viewportContent: viewportMeta,
-      hasMediaQueries,
-      mediaQueryCount: allMediaQueries.length,
-      mediaQuerySources: {
-        inline: inlineCount,
-        external: externalSources,
-      },
-      breakpoints,
-      hasMobileBreakpoint: hasMobile,
-      hasTabletBreakpoint: hasTablet,
-      hasDesktopBreakpoint: hasDesktop,
-    },
-  };
-}