@rankcli/agent-runtime 0.0.1

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

@@ -0,0 +1,420 @@
+// 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

@@ -0,0 +1,247 @@
+/**
+ * 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,
+    },
+  };
+}