@rankcli/agent-runtime 0.0.1

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

@@ -0,0 +1,226 @@
+// Modern Image Format Checks
+// Checks for WebP/AVIF usage and image optimization
+
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+import { ISSUE_DEFINITIONS } from '../types.js';
+
+// File extensions for modern formats
+const MODERN_FORMATS = ['.webp', '.avif'];
+const LEGACY_FORMATS = ['.jpg', '.jpeg', '.png', '.gif', '.bmp'];
+
+export interface ImageInfo {
+  src: string;
+  alt: string | null;
+  width: number | null;
+  height: number | null;
+  loading: string | null;
+  format: string;
+  isModernFormat: boolean;
+  hasDimensions: boolean;
+  isLazyLoaded: boolean;
+}
+
+export interface ModernImagesData {
+  totalImages: number;
+  modernFormatCount: number;
+  legacyFormatCount: number;
+  modernFormatPercentage: number;
+  images: ImageInfo[];
+  hasSourceSet: boolean;
+  hasPictureElements: boolean;
+}
+
+/**
+ * Extract format from URL
+ */
+function getImageFormat(url: string): string {
+  try {
+    const pathname = new URL(url, 'https://example.com').pathname.toLowerCase();
+
+    // Check for format in query string (common with CDNs)
+    const formatMatch = url.match(/[?&](?:format|f)=(\w+)/i);
+    if (formatMatch) {
+      return '.' + formatMatch[1].toLowerCase();
+    }
+
+    // Check file extension
+    const extMatch = pathname.match(/\.([a-z0-9]+)$/i);
+    if (extMatch) {
+      return '.' + extMatch[1].toLowerCase();
+    }
+
+    return 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Check if format is modern
+ */
+function isModernFormat(format: string): boolean {
+  return MODERN_FORMATS.includes(format.toLowerCase());
+}
+
+/**
+ * Extract image information from HTML
+ */
+function extractImages($: cheerio.CheerioAPI, baseUrl: string): ImageInfo[] {
+  const images: ImageInfo[] = [];
+
+  // Process img tags
+  $('img').each((_, el) => {
+    const src = $(el).attr('src') || $(el).attr('data-src') || '';
+    const srcset = $(el).attr('srcset') || '';
+    const alt = $(el).attr('alt') || null;
+    const width = $(el).attr('width') ? parseInt($(el).attr('width')!, 10) : null;
+    const height = $(el).attr('height') ? parseInt($(el).attr('height')!, 10) : null;
+    const loading = $(el).attr('loading') || null;
+
+    // Skip data URIs and empty sources
+    if (!src || src.startsWith('data:')) return;
+
+    // Resolve relative URLs
+    let fullSrc = src;
+    try {
+      fullSrc = new URL(src, baseUrl).href;
+    } catch {
+      // Keep original if URL parsing fails
+    }
+
+    const format = getImageFormat(fullSrc);
+
+    images.push({
+      src: fullSrc,
+      alt,
+      width,
+      height,
+      loading,
+      format,
+      isModernFormat: isModernFormat(format),
+      hasDimensions: width !== null && height !== null,
+      isLazyLoaded: loading === 'lazy' || $(el).attr('data-src') !== undefined,
+    });
+
+    // Check srcset for modern formats
+    if (srcset) {
+      const srcsetUrls = srcset.split(',').map((s) => s.trim().split(' ')[0]);
+      for (const srcsetUrl of srcsetUrls) {
+        const srcsetFormat = getImageFormat(srcsetUrl);
+        if (isModernFormat(srcsetFormat) && !images.some((img) => img.src === srcsetUrl)) {
+          images.push({
+            src: srcsetUrl,
+            alt,
+            width: null,
+            height: null,
+            loading,
+            format: srcsetFormat,
+            isModernFormat: true,
+            hasDimensions: false,
+            isLazyLoaded: loading === 'lazy',
+          });
+        }
+      }
+    }
+  });
+
+  // Check picture elements for modern format sources
+  $('picture source').each((_, el) => {
+    const srcset = $(el).attr('srcset') || '';
+    const type = $(el).attr('type') || '';
+
+    if (type.includes('webp') || type.includes('avif')) {
+      const srcsetUrls = srcset.split(',').map((s) => s.trim().split(' ')[0]);
+      for (const srcsetUrl of srcsetUrls) {
+        if (!images.some((img) => img.src === srcsetUrl)) {
+          images.push({
+            src: srcsetUrl,
+            alt: null,
+            width: null,
+            height: null,
+            loading: null,
+            format: type.includes('webp') ? '.webp' : '.avif',
+            isModernFormat: true,
+            hasDimensions: false,
+            isLazyLoaded: false,
+          });
+        }
+      }
+    }
+  });
+
+  return images;
+}
+
+/**
+ * Analyze image formats and optimization
+ */
+export function analyzeModernImages(html: string, url: string): { issues: AuditIssue[]; data: ModernImagesData } {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+
+  // Extract images
+  const images = extractImages($, url);
+
+  // Filter to unique images by src
+  const uniqueImages = images.filter((img, idx, arr) => arr.findIndex((i) => i.src === img.src) === idx);
+
+  // Count formats
+  const modernFormatCount = uniqueImages.filter((img) => img.isModernFormat).length;
+  const legacyFormatCount = uniqueImages.filter(
+    (img) => !img.isModernFormat && LEGACY_FORMATS.includes(img.format)
+  ).length;
+
+  // Check for picture elements and srcset
+  const hasPictureElements = $('picture').length > 0;
+  const hasSourceSet = $('img[srcset]').length > 0 || $('picture source[srcset]').length > 0;
+
+  // Calculate percentage
+  const totalRelevantImages = modernFormatCount + legacyFormatCount;
+  const modernFormatPercentage = totalRelevantImages > 0 ? Math.round((modernFormatCount / totalRelevantImages) * 100) : 100;
+
+  // Generate issues
+  if (legacyFormatCount > 0 && !hasPictureElements && !hasSourceSet) {
+    const legacyImages = uniqueImages.filter((img) => !img.isModernFormat && LEGACY_FORMATS.includes(img.format));
+
+    issues.push({
+      ...ISSUE_DEFINITIONS.IMAGE_NOT_WEBP_AVIF,
+      affectedUrls: legacyImages.slice(0, 10).map((img) => img.src),
+      details: {
+        legacyImageCount: legacyFormatCount,
+        modernImageCount: modernFormatCount,
+        modernFormatPercentage,
+        recommendation: 'Convert images to WebP or AVIF format for 25-50% smaller file sizes',
+      },
+    });
+  }
+
+  // Check for images without dimensions (causes CLS)
+  const imagesWithoutDimensions = uniqueImages.filter(
+    (img) => !img.hasDimensions && !img.isLazyLoaded && LEGACY_FORMATS.includes(img.format)
+  );
+
+  if (imagesWithoutDimensions.length > 0) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.IMG_NO_DIMENSIONS,
+      affectedUrls: imagesWithoutDimensions.slice(0, 10).map((img) => img.src),
+      details: {
+        count: imagesWithoutDimensions.length,
+      },
+    });
+  }
+
+  return {
+    issues,
+    data: {
+      totalImages: uniqueImages.length,
+      modernFormatCount,
+      legacyFormatCount,
+      modernFormatPercentage,
+      images: uniqueImages,
+      hasSourceSet,
+      hasPictureElements,
+    },
+  };
+}

package/src/audit/checks/navboost-signals.ts

@@ -0,0 +1,395 @@
+// NavBoost & User Signal Optimization
+// Reference: Google Algorithm Leak 2024 + DOJ vs Google Antitrust Trial
+// NavBoost uses memorized click data over 13 months
+// "goodClicks", "badClicks", "lastLongestClicks" - confirmed ranking signals
+// Bounce rate >70% + session <30 seconds = quality signal problem
+
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+
+export interface NavBoostSignalsData {
+  clickOptimization: {
+    hasClearTitle: boolean;
+    hasCompellingMetaDesc: boolean;
+    titleTruncated: boolean;
+    metaDescTruncated: boolean;
+    estimatedCTRPotential: 'high' | 'medium' | 'low';
+  };
+  engagementSignals: {
+    hasTableOfContents: boolean;
+    hasJumpLinks: boolean;
+    estimatedScrollDepth: 'deep' | 'medium' | 'shallow';
+    hasProgressIndicator: boolean;
+    hasStickyNavigation: boolean;
+    contentSections: number;
+  };
+  bounceRiskFactors: {
+    hasAboveFoldContent: boolean;
+    hasSlowLoadingIndicators: boolean;
+    hasPopupRisk: boolean;
+    hasIntrusiveAds: boolean;
+    contentMatchesTitle: boolean;
+    hasImmediateValue: boolean;
+  };
+  dwellTimeFactors: {
+    estimatedReadTime: number; // minutes
+    hasVideo: boolean;
+    hasInteractiveElements: boolean;
+    contentDepth: 'comprehensive' | 'moderate' | 'thin';
+    hasRelatedContent: boolean;
+  };
+  overallNavBoostScore: number; // 0-100
+  recommendations: string[];
+}
+
+/**
+ * Analyze title and meta description for CTR optimization
+ */
+function analyzeClickOptimization($: cheerio.CheerioAPI): NavBoostSignalsData['clickOptimization'] {
+  const title = $('title').text().trim();
+  const metaDesc = $('meta[name="description"]').attr('content')?.trim() || '';
+
+  // Title analysis
+  const hasClearTitle = title.length > 10 && title.length <= 60;
+  const titleTruncated = title.length > 60;
+
+  // Meta description analysis
+  const hasCompellingMetaDesc = metaDesc.length >= 70 && metaDesc.length <= 160;
+  const metaDescTruncated = metaDesc.length > 160;
+
+  // CTR potential indicators
+  const hasPowerWords = /free|best|guide|how to|ultimate|proven|secret|new|exclusive/i.test(title + ' ' + metaDesc);
+  const hasNumbers = /\d+/.test(title);
+  const hasYear = /202[4-9]|203\d/.test(title + ' ' + metaDesc);
+
+  let ctrScore = 0;
+  if (hasClearTitle) ctrScore += 2;
+  if (hasCompellingMetaDesc) ctrScore += 2;
+  if (hasPowerWords) ctrScore += 1;
+  if (hasNumbers) ctrScore += 1;
+  if (hasYear) ctrScore += 1;
+
+  const estimatedCTRPotential = ctrScore >= 5 ? 'high' : ctrScore >= 3 ? 'medium' : 'low';
+
+  return {
+    hasClearTitle,
+    hasCompellingMetaDesc,
+    titleTruncated,
+    metaDescTruncated,
+    estimatedCTRPotential,
+  };
+}
+
+/**
+ * Analyze engagement signals that affect NavBoost
+ */
+function analyzeEngagementSignals($: cheerio.CheerioAPI, html: string): NavBoostSignalsData['engagementSignals'] {
+  // Table of contents detection
+  const hasTableOfContents =
+    $('[class*="toc"], [id*="toc"], [class*="table-of-contents"], nav[aria-label*="content"]').length > 0 ||
+    $('a[href^="#"]').filter((_, el) => {
+      const text = $(el).text().toLowerCase();
+      return /^(\d+\.?\s*)?[a-z]/i.test(text) && text.length > 3;
+    }).length >= 3;
+
+  // Jump links (in-page navigation)
+  const hasJumpLinks = $('a[href^="#"]').length >= 3;
+
+  // Count content sections (H2s as proxy)
+  const contentSections = $('h2, h3').length;
+
+  // Scroll depth estimation based on content length
+  const bodyText = $('body').text();
+  const wordCount = bodyText.split(/\s+/).filter(w => w.length > 0).length;
+  const estimatedScrollDepth = wordCount > 2000 ? 'deep' : wordCount > 800 ? 'medium' : 'shallow';
+
+  // Progress indicator
+  const hasProgressIndicator =
+    $('[class*="progress"], [class*="reading-progress"], [role="progressbar"]').length > 0;
+
+  // Sticky navigation
+  const hasStickyNavigation =
+    $('[class*="sticky"], [class*="fixed"], [style*="position: sticky"], [style*="position: fixed"]').filter((_, el) => {
+      return $(el).find('nav, a').length > 0;
+    }).length > 0;
+
+  return {
+    hasTableOfContents,
+    hasJumpLinks,
+    estimatedScrollDepth,
+    hasProgressIndicator,
+    hasStickyNavigation,
+    contentSections,
+  };
+}
+
+/**
+ * Analyze bounce risk factors
+ */
+function analyzeBounceRiskFactors($: cheerio.CheerioAPI, html: string): NavBoostSignalsData['bounceRiskFactors'] {
+  const title = $('title').text().toLowerCase();
+  const h1 = $('h1').first().text().toLowerCase();
+  const firstParagraph = $('p').first().text().toLowerCase();
+
+  // Above fold content check
+  const hasAboveFoldContent =
+    $('h1').length > 0 &&
+    ($('p').first().text().length > 50 ||
+     $('main, article, .content').first().text().length > 100);
+
+  // Slow loading indicators (large images, heavy scripts)
+  const hasSlowLoadingIndicators =
+    $('script[src*="bundle"], script[src*="vendor"]').length > 5 ||
+    $('img:not([loading="lazy"])').length > 10;
+
+  // Popup risk
+  const hasPopupRisk =
+    html.includes('modal') ||
+    html.includes('popup') ||
+    html.includes('newsletter-overlay') ||
+    $('[class*="popup"], [class*="modal"]').length > 0;
+
+  // Intrusive ads
+  const hasIntrusiveAds =
+    $('[class*="ad-"], [id*="ad-"], [class*="advertisement"]').length > 3 ||
+    html.includes('interstitial');
+
+  // Content-title match (basic check)
+  const titleWords = title.split(/\s+/).filter(w => w.length > 3);
+  const matchingWords = titleWords.filter(w =>
+    h1.includes(w) || firstParagraph.includes(w)
+  );
+  const contentMatchesTitle = matchingWords.length >= Math.ceil(titleWords.length * 0.5);
+
+  // Immediate value (answer in first paragraph)
+  const hasImmediateValue =
+    firstParagraph.length > 100 ||
+    $('main p, article p').first().text().length > 100;
+
+  return {
+    hasAboveFoldContent,
+    hasSlowLoadingIndicators,
+    hasPopupRisk,
+    hasIntrusiveAds,
+    contentMatchesTitle,
+    hasImmediateValue,
+  };
+}
+
+/**
+ * Analyze dwell time factors
+ */
+function analyzeDwellTimeFactors($: cheerio.CheerioAPI, html: string): NavBoostSignalsData['dwellTimeFactors'] {
+  const bodyText = $('main, article, .content, body').text();
+  const wordCount = bodyText.split(/\s+/).filter(w => w.length > 0).length;
+
+  // Estimated read time (200 words per minute average)
+  const estimatedReadTime = Math.ceil(wordCount / 200);
+
+  // Video presence
+  const hasVideo =
+    $('video, iframe[src*="youtube"], iframe[src*="vimeo"], [class*="video"]').length > 0;
+
+  // Interactive elements
+  const hasInteractiveElements =
+    $('form, [class*="calculator"], [class*="quiz"], [class*="interactive"], input, select').length > 0;
+
+  // Content depth
+  const contentDepth = wordCount > 2000 ? 'comprehensive' : wordCount > 800 ? 'moderate' : 'thin';
+
+  // Related content
+  const hasRelatedContent =
+    $('[class*="related"], [class*="recommended"], [class*="similar"]').length > 0 ||
+    $('a').filter((_, el) => {
+      const text = $(el).text().toLowerCase();
+      return text.includes('related') || text.includes('see also') || text.includes('read next');
+    }).length > 0;
+
+  return {
+    estimatedReadTime,
+    hasVideo,
+    hasInteractiveElements,
+    contentDepth,
+    hasRelatedContent,
+  };
+}
+
+/**
+ * Calculate overall NavBoost optimization score
+ */
+function calculateNavBoostScore(
+  click: NavBoostSignalsData['clickOptimization'],
+  engagement: NavBoostSignalsData['engagementSignals'],
+  bounce: NavBoostSignalsData['bounceRiskFactors'],
+  dwell: NavBoostSignalsData['dwellTimeFactors']
+): number {
+  let score = 50; // Start at baseline
+
+  // Click optimization (max +20)
+  if (click.estimatedCTRPotential === 'high') score += 20;
+  else if (click.estimatedCTRPotential === 'medium') score += 10;
+  if (click.titleTruncated) score -= 5;
+  if (click.metaDescTruncated) score -= 3;
+
+  // Engagement signals (max +20)
+  if (engagement.hasTableOfContents) score += 10;
+  if (engagement.hasJumpLinks) score += 5;
+  if (engagement.contentSections >= 5) score += 5;
+
+  // Bounce risk (max -20)
+  if (!bounce.hasAboveFoldContent) score -= 10;
+  if (bounce.hasPopupRisk) score -= 5;
+  if (bounce.hasIntrusiveAds) score -= 10;
+  if (!bounce.contentMatchesTitle) score -= 5;
+  if (bounce.hasImmediateValue) score += 5;
+
+  // Dwell time factors (max +20)
+  if (dwell.hasVideo) score += 10;
+  if (dwell.hasInteractiveElements) score += 5;
+  if (dwell.contentDepth === 'comprehensive') score += 5;
+  else if (dwell.contentDepth === 'thin') score -= 5;
+  if (dwell.hasRelatedContent) score += 5;
+
+  return Math.max(0, Math.min(100, score));
+}
+
+/**
+ * Main function: Analyze NavBoost optimization signals
+ */
+export function analyzeNavBoostSignals(
+  html: string,
+  url: string
+): { issues: AuditIssue[]; data: NavBoostSignalsData } {
+  const $ = cheerio.load(html);
+  const issues: AuditIssue[] = [];
+
+  // Run all analyses
+  const clickOptimization = analyzeClickOptimization($);
+  const engagementSignals = analyzeEngagementSignals($, html);
+  const bounceRiskFactors = analyzeBounceRiskFactors($, html);
+  const dwellTimeFactors = analyzeDwellTimeFactors($, html);
+
+  // Calculate overall score
+  const overallNavBoostScore = calculateNavBoostScore(
+    clickOptimization,
+    engagementSignals,
+    bounceRiskFactors,
+    dwellTimeFactors
+  );
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+
+  if (clickOptimization.estimatedCTRPotential !== 'high') {
+    recommendations.push('Optimize title/meta for higher CTR: use power words, numbers, or current year');
+  }
+  if (!engagementSignals.hasTableOfContents && engagementSignals.contentSections >= 5) {
+    recommendations.push('Add table of contents for long-form content to improve engagement');
+  }
+  if (bounceRiskFactors.hasPopupRisk) {
+    recommendations.push('Delay or remove popup modals to reduce bounce rate');
+  }
+  if (!dwellTimeFactors.hasRelatedContent) {
+    recommendations.push('Add related content section to increase session duration');
+  }
+
+  // Generate issues
+
+  // Low CTR potential
+  if (clickOptimization.estimatedCTRPotential === 'low') {
+    issues.push({
+      code: 'LOW_CTR_POTENTIAL',
+      severity: 'warning',
+      category: 'on-page',
+      title: 'Title and meta description have low CTR potential',
+      description: 'The title and meta description lack compelling elements that drive clicks.',
+      impact: 'NavBoost uses click data as a ranking signal. Higher CTR improves rankings over time.',
+      howToFix: 'Add power words (free, best, ultimate), numbers, or current year to increase CTR.',
+      affectedUrls: [url],
+      details: {
+        ctrPotential: clickOptimization.estimatedCTRPotential,
+        titleTruncated: clickOptimization.titleTruncated,
+      },
+    });
+  }
+
+  // High bounce risk
+  if (!bounceRiskFactors.hasAboveFoldContent || !bounceRiskFactors.hasImmediateValue) {
+    issues.push({
+      code: 'HIGH_BOUNCE_RISK',
+      severity: 'warning',
+      category: 'content',
+      title: 'Page has high bounce risk signals',
+      description: 'The page lacks above-fold content or immediate value for visitors.',
+      impact: 'NavBoost tracks bounce rate. >70% bounce with <30s sessions hurts rankings.',
+      howToFix: 'Add compelling content above the fold that delivers immediate value to visitors.',
+      affectedUrls: [url],
+      details: {
+        hasAboveFoldContent: bounceRiskFactors.hasAboveFoldContent,
+        hasImmediateValue: bounceRiskFactors.hasImmediateValue,
+      },
+    });
+  }
+
+  // Popup/interstitial risk
+  if (bounceRiskFactors.hasPopupRisk) {
+    issues.push({
+      code: 'POPUP_BOUNCE_RISK',
+      severity: 'notice',
+      category: 'content',
+      title: 'Popup/modal detected - potential bounce risk',
+      description: 'Popups detected that may cause visitors to leave immediately.',
+      impact: 'Intrusive interstitials increase bounce rate and hurt NavBoost signals.',
+      howToFix: 'Delay popups by 30+ seconds, or use exit-intent only. Avoid fullscreen overlays.',
+      affectedUrls: [url],
+    });
+  }
+
+  // Thin content with low dwell time
+  if (dwellTimeFactors.contentDepth === 'thin' && dwellTimeFactors.estimatedReadTime < 3) {
+    issues.push({
+      code: 'LOW_DWELL_TIME_CONTENT',
+      severity: 'notice',
+      category: 'content',
+      title: 'Thin content may result in low dwell time',
+      description: `Estimated read time is only ${dwellTimeFactors.estimatedReadTime} minute(s).`,
+      impact: 'Google tracks "lastLongestClicks" - longer sessions signal quality content.',
+      howToFix: 'Add comprehensive content, videos, or interactive elements to increase time on page.',
+      affectedUrls: [url],
+      details: {
+        estimatedReadTime: dwellTimeFactors.estimatedReadTime,
+        contentDepth: dwellTimeFactors.contentDepth,
+      },
+    });
+  }
+
+  // Long content without navigation aids
+  if (engagementSignals.estimatedScrollDepth === 'deep' && !engagementSignals.hasTableOfContents) {
+    issues.push({
+      code: 'LONG_CONTENT_NO_TOC',
+      severity: 'notice',
+      category: 'content',
+      title: 'Long content lacks table of contents',
+      description: 'Long-form content without navigation aids may cause users to abandon the page.',
+      impact: 'Table of contents improves engagement signals by helping users find relevant sections.',
+      howToFix: 'Add a table of contents with jump links to major sections.',
+      affectedUrls: [url],
+      details: {
+        contentSections: engagementSignals.contentSections,
+        scrollDepth: engagementSignals.estimatedScrollDepth,
+      },
+    });
+  }
+
+  return {
+    issues,
+    data: {
+      clickOptimization,
+      engagementSignals,
+      bounceRiskFactors,
+      dwellTimeFactors,
+      overallNavBoostScore,
+      recommendations,
+    },
+  };
+}