@rankcli/agent-runtime 0.0.1

package/src/audit/checks/client-rendering.ts

@@ -0,0 +1,542 @@
+// Client-Side Rendering Detection - SSR/SSG is critical for SEO
+// Reference: "Technical SEO for Developers - 17 Tips to Rank Higher"
+// "The page should load its content even if I have JavaScript disabled"
+// "Statically generating or server-side rendering is so much safer than rendering only on the client"
+
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+
+export interface RenderingAnalysis {
+  renderingMethod: 'ssr' | 'ssg' | 'csr' | 'hybrid' | 'unknown';
+  confidence: 'high' | 'medium' | 'low';
+  signals: RenderingSignal[];
+  frameworkDetected: string | null;
+  hasContentInHTML: boolean;
+  hasHydrationMarkers: boolean;
+  hasClientOnlyIndicators: boolean;
+  mainContentCharCount: number;
+  recommendations: string[];
+  metaManagement: string | null; // React Helmet, Vue Meta, etc.
+  hasDynamicMetaTags: boolean;
+  // AI-specific content accessibility metrics
+  aiAccessibility: {
+    htmlContentRatio: number; // % of content in raw HTML vs total expected
+    hasSemanticStructure: boolean; // Proper heading hierarchy, landmarks
+    keyContentInHTML: boolean; // Title, main headings, first paragraphs in HTML
+    aiReadableScore: number; // 0-100 score for AI parsing ability
+  };
+}
+
+export interface RenderingSignal {
+  indicator: string;
+  suggests: 'ssr' | 'ssg' | 'csr';
+  weight: number;
+}
+
+// Framework detection patterns
+const FRAMEWORK_PATTERNS: Record<string, RegExp[]> = {
+  'Next.js': [/__NEXT_DATA__/, /next\//, /_next\//],
+  'Nuxt': [/__NUXT__/, /nuxt/, /_nuxt\//],
+  'Gatsby': [/___gatsby/, /gatsby-/, /gatsby-image/],
+  'Remix': [/__remix/, /remix/],
+  'SvelteKit': [/__sveltekit/, /svelte/],
+  'Angular Universal': [/ng-version/, /angular/],
+  'React': [/react-root/, /data-reactroot/, /__REACT/],
+  'Vue': [/data-v-/, /Vue\./, /__VUE/],
+  'Astro': [/astro-/, /astro:/],
+};
+
+// Meta tag management patterns (React Helmet, etc.)
+const META_MANAGEMENT_PATTERNS = [
+  { name: 'React Helmet', pattern: /data-react-helmet/i },
+  { name: 'Next.js Head', pattern: /__NEXT_DATA__.*"head"/i },
+  { name: 'Vue Meta', pattern: /data-vue-meta/i },
+  { name: 'Nuxt Head', pattern: /__NUXT__.*"head"/i },
+  { name: 'Remix Meta', pattern: /__remix_meta/i },
+];
+
+// Indicators of client-side only rendering (bad for SEO)
+const CSR_INDICATORS = [
+  // Empty root elements waiting for JS to populate
+  { pattern: /<div id="root"><\/div>/i, weight: 3 },
+  { pattern: /<div id="app"><\/div>/i, weight: 3 },
+  { pattern: /<div id="__next"><\/div>/i, weight: 2 }, // Empty Next.js (should have content)
+  { pattern: /<div id="__nuxt"><\/div>/i, weight: 2 }, // Empty Nuxt
+  { pattern: /<main><\/main>/i, weight: 2 },
+  { pattern: /<article><\/article>/i, weight: 2 },
+
+  // Noscript warnings indicating JS dependency
+  { pattern: /<noscript>.*(?:enable|require|need).*javascript/i, weight: 3 },
+  { pattern: /<noscript>.*(?:won't work|doesn't work)/i, weight: 3 },
+
+  // Very minimal HTML body
+  { pattern: /<body[^>]*>\s*<(?:div|script)[^>]*>\s*<\/(?:div|script)>\s*<\/body>/i, weight: 4 },
+
+  // Loading spinners/states in initial HTML
+  { pattern: /class="[^"]*loading[^"]*"/i, weight: 1 },
+  { pattern: /Loading\.\.\./i, weight: 1 },
+
+  // Client-only component indicators
+  { pattern: /data-client-only/i, weight: 2 },
+  { pattern: /client:only/i, weight: 2 }, // Astro client:only
+];
+
+// Indicators of server-side rendering (good for SEO)
+const SSR_INDICATORS = [
+  // Hydration markers (content was rendered server-side)
+  { pattern: /__NEXT_DATA__/, weight: 3 },
+  { pattern: /__NUXT__/, weight: 3 },
+  { pattern: /data-reactroot/, weight: 2 },
+  { pattern: /data-server-rendered/, weight: 3 },
+
+  // Pre-rendered content indicators
+  { pattern: /<h1[^>]*>[^<]+<\/h1>/i, weight: 2 },
+  { pattern: /<article[^>]*>[^<]{100,}/i, weight: 3 },
+  { pattern: /<main[^>]*>[^<]{100,}/i, weight: 3 },
+
+  // Meta content (usually server-rendered)
+  { pattern: /<meta property="og:title"[^>]*content="[^"]+"/, weight: 1 },
+  { pattern: /<meta name="description"[^>]*content="[^"]+"/, weight: 1 },
+
+  // Structured data
+  { pattern: /<script type="application\/ld\+json">/, weight: 2 },
+];
+
+/**
+ * Detect framework from HTML
+ */
+export function detectFramework(html: string): string | null {
+  for (const [framework, patterns] of Object.entries(FRAMEWORK_PATTERNS)) {
+    for (const pattern of patterns) {
+      if (pattern.test(html)) {
+        return framework;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Analyze HTML to determine rendering method
+ */
+export function analyzeRendering(html: string): RenderingAnalysis {
+  const $ = cheerio.load(html);
+  const signals: RenderingSignal[] = [];
+
+  // Detect framework
+  const frameworkDetected = detectFramework(html);
+
+  // Check for CSR indicators
+  let csrScore = 0;
+  for (const indicator of CSR_INDICATORS) {
+    if (indicator.pattern.test(html)) {
+      csrScore += indicator.weight;
+      signals.push({
+        indicator: indicator.pattern.toString(),
+        suggests: 'csr',
+        weight: indicator.weight,
+      });
+    }
+  }
+
+  // Check for SSR indicators
+  let ssrScore = 0;
+  for (const indicator of SSR_INDICATORS) {
+    if (indicator.pattern.test(html)) {
+      ssrScore += indicator.weight;
+      signals.push({
+        indicator: indicator.pattern.toString(),
+        suggests: 'ssr',
+        weight: indicator.weight,
+      });
+    }
+  }
+
+  // Analyze main content
+  const mainContent = $('main, article, [role="main"], .content, #content').text();
+  const bodyText = $('body').text().replace(/\s+/g, ' ').trim();
+  const mainContentCharCount = mainContent.length || bodyText.length;
+
+  // Very little text content is a red flag
+  const hasContentInHTML = mainContentCharCount > 200;
+  if (!hasContentInHTML) {
+    csrScore += 4;
+    signals.push({
+      indicator: `Body text only ${mainContentCharCount} chars`,
+      suggests: 'csr',
+      weight: 4,
+    });
+  } else {
+    ssrScore += 2;
+  }
+
+  // Check for hydration markers
+  const hasHydrationMarkers =
+    /__NEXT_DATA__|__NUXT__|data-reactroot|data-server-rendered/.test(html);
+
+  // Check for client-only indicators
+  const hasClientOnlyIndicators = $('[data-client-only], [client\\:only]').length > 0;
+
+  // Detect meta tag management library
+  let metaManagement: string | null = null;
+  for (const { name, pattern } of META_MANAGEMENT_PATTERNS) {
+    if (pattern.test(html)) {
+      metaManagement = name;
+      break;
+    }
+  }
+
+  // Check if meta tags appear to be dynamically managed
+  const hasDynamicMetaTags = metaManagement !== null ||
+    $('meta[data-react-helmet]').length > 0 ||
+    $('meta[data-vue-meta]').length > 0;
+
+  // === AI ACCESSIBILITY ANALYSIS ===
+  // AI systems (ChatGPT, Claude, etc.) primarily read raw HTML
+  // Content hidden behind JavaScript may not be indexed by AI
+
+  // Check semantic structure
+  const hasH1 = $('h1').length > 0 && $('h1').text().trim().length > 0;
+  const hasH2 = $('h2').length > 0;
+  const hasMain = $('main, [role="main"]').length > 0;
+  const hasArticle = $('article').length > 0;
+  const hasSemanticStructure = hasH1 && (hasMain || hasArticle);
+
+  // Check if key content is in HTML
+  const title = $('title').text().trim();
+  const h1Text = $('h1').first().text().trim();
+  const firstParagraph = $('p').first().text().trim();
+
+  const keyContentInHTML =
+    title.length > 10 &&
+    h1Text.length > 5 &&
+    firstParagraph.length > 50;
+
+  // Calculate HTML content ratio
+  // Compare actual content to expected minimum for a meaningful page
+  const EXPECTED_MIN_CONTENT = 1000; // Minimum expected chars for a content page
+  const htmlContentRatio = Math.min(100, (mainContentCharCount / EXPECTED_MIN_CONTENT) * 100);
+
+  // Calculate AI readable score
+  let aiReadableScore = 50; // Base score
+
+  // Content amount
+  if (mainContentCharCount > 2000) aiReadableScore += 20;
+  else if (mainContentCharCount > 1000) aiReadableScore += 15;
+  else if (mainContentCharCount > 500) aiReadableScore += 10;
+  else if (mainContentCharCount < 200) aiReadableScore -= 20;
+
+  // Semantic structure
+  if (hasSemanticStructure) aiReadableScore += 15;
+  if (hasH1 && hasH2) aiReadableScore += 5;
+
+  // Key content in HTML
+  if (keyContentInHTML) aiReadableScore += 15;
+  else aiReadableScore -= 10;
+
+  // SSR/SSG bonus
+  if (hasHydrationMarkers || ssrScore > csrScore) aiReadableScore += 10;
+
+  // CSR penalty
+  if (csrScore > ssrScore + 3) aiReadableScore -= 20;
+
+  aiReadableScore = Math.max(0, Math.min(100, aiReadableScore));
+
+  const aiAccessibility = {
+    htmlContentRatio: Math.round(htmlContentRatio),
+    hasSemanticStructure,
+    keyContentInHTML,
+    aiReadableScore,
+  };
+
+  // Determine rendering method
+  let renderingMethod: 'ssr' | 'ssg' | 'csr' | 'hybrid' | 'unknown';
+  let confidence: 'high' | 'medium' | 'low';
+
+  if (csrScore > ssrScore + 3) {
+    renderingMethod = 'csr';
+    confidence = csrScore - ssrScore > 6 ? 'high' : 'medium';
+  } else if (ssrScore > csrScore + 3) {
+    // Distinguish SSG from SSR (static has specific patterns)
+    const isLikelyStatic =
+      html.includes('data-gatsby') ||
+      html.includes('astro-') ||
+      (!html.includes('__NEXT_DATA__') && !html.includes('__NUXT__'));
+
+    renderingMethod = isLikelyStatic ? 'ssg' : 'ssr';
+    confidence = ssrScore - csrScore > 6 ? 'high' : 'medium';
+  } else if (hasHydrationMarkers && hasClientOnlyIndicators) {
+    renderingMethod = 'hybrid';
+    confidence = 'medium';
+  } else {
+    renderingMethod = 'unknown';
+    confidence = 'low';
+  }
+
+  // Generate recommendations
+  const recommendations = generateRecommendations(
+    renderingMethod,
+    hasContentInHTML,
+    mainContentCharCount,
+    frameworkDetected
+  );
+
+  return {
+    renderingMethod,
+    confidence,
+    signals,
+    frameworkDetected,
+    hasContentInHTML,
+    hasHydrationMarkers,
+    hasClientOnlyIndicators,
+    mainContentCharCount,
+    recommendations,
+    metaManagement,
+    hasDynamicMetaTags,
+    aiAccessibility,
+  };
+}
+
+function generateRecommendations(
+  renderingMethod: string,
+  hasContentInHTML: boolean,
+  charCount: number,
+  framework: string | null
+): string[] {
+  const recommendations: string[] = [];
+
+  if (renderingMethod === 'csr') {
+    recommendations.push(
+      'Critical: Pre-render your pages so crawlers see actual content in the HTML'
+    );
+
+    if (framework === 'React') {
+      recommendations.push(
+        'Quick fix: Add react-snap to pre-render pages at build time (npm install -D react-snap, add "postbuild": "react-snap" to scripts)'
+      );
+      recommendations.push(
+        'Alternative: Use Vike (vite-plugin-ssr) for SSR/SSG without changing frameworks'
+      );
+    } else if (framework === 'Vue') {
+      recommendations.push(
+        'Quick fix: Add prerender-spa-plugin to pre-render pages at build time'
+      );
+      recommendations.push(
+        'Alternative: Use Vike (vite-plugin-ssr) for SSR/SSG without changing frameworks'
+      );
+    } else if (framework === 'Angular Universal') {
+      recommendations.push(
+        'Enable Angular Universal for server-side rendering'
+      );
+    } else {
+      recommendations.push(
+        'Quick fix: Use a pre-rendering tool like react-snap or prerender-spa-plugin'
+      );
+    }
+
+    recommendations.push(
+      'Google can render JavaScript, but pre-rendered HTML is more reliable and faster to index'
+    );
+  }
+
+  if (!hasContentInHTML) {
+    recommendations.push(
+      `Very little content in initial HTML (${charCount} chars). Search engines may not see your content.`
+    );
+  }
+
+  if (renderingMethod === 'hybrid') {
+    recommendations.push(
+      'Hybrid rendering detected. Ensure critical SEO content is server-rendered, not client-only.'
+    );
+  }
+
+  return recommendations;
+}
+
+/**
+ * Main function: Analyze page rendering method for SEO
+ */
+export function analyzeClientRendering(
+  html: string,
+  url: string
+): { issues: AuditIssue[]; data: RenderingAnalysis } {
+  const $ = cheerio.load(html);
+  const issues: AuditIssue[] = [];
+  const analysis = analyzeRendering(html);
+
+  // Critical: Client-side only rendering
+  if (analysis.renderingMethod === 'csr' && analysis.confidence !== 'low') {
+    const howToFixByFramework = analysis.frameworkDetected === 'React'
+      ? 'Add react-snap to pre-render pages: npm install -D react-snap, then add "postbuild": "react-snap" to package.json scripts. No code changes needed.'
+      : analysis.frameworkDetected === 'Vue'
+      ? 'Add prerender-spa-plugin to pre-render pages at build time. Alternatively, use Vike for SSR/SSG.'
+      : 'Pre-render your pages using react-snap, prerender-spa-plugin, or similar build-time tools.';
+
+    issues.push({
+      code: 'CLIENT_SIDE_RENDERING',
+      severity: 'error',
+      category: 'crawlability',
+      title: 'Page relies on client-side rendering',
+      description:
+        'This page appears to render content primarily via JavaScript. Search engines may not see your content.',
+      impact:
+        'Google can execute JavaScript but it\'s slower and less reliable. Content may not be indexed properly.',
+      howToFix: howToFixByFramework,
+      affectedUrls: [url],
+      details: {
+        confidence: analysis.confidence,
+        framework: analysis.frameworkDetected,
+        signals: analysis.signals.filter(s => s.suggests === 'csr').slice(0, 5),
+      },
+    });
+  }
+
+  // Warning: Very little content in HTML
+  if (!analysis.hasContentInHTML) {
+    issues.push({
+      code: 'EMPTY_BODY_CONTENT',
+      severity: 'error',
+      category: 'content',
+      title: 'Very little content in initial HTML',
+      description:
+        `Only ${analysis.mainContentCharCount} characters of text found in the HTML. Content may be loaded via JavaScript.`,
+      impact:
+        'Search engines prioritize content in the initial HTML response. JavaScript-loaded content may be missed or delayed.',
+      howToFix:
+        'Ensure main page content is present in the server-rendered HTML, not loaded via JavaScript after page load.',
+      affectedUrls: [url],
+      details: {
+        charCount: analysis.mainContentCharCount,
+        renderingMethod: analysis.renderingMethod,
+      },
+    });
+  }
+
+  // Notice: Framework without SSR evidence
+  if (
+    analysis.frameworkDetected &&
+    ['React', 'Vue'].includes(analysis.frameworkDetected) &&
+    !analysis.hasHydrationMarkers &&
+    analysis.mainContentCharCount < 500
+  ) {
+    issues.push({
+      code: 'SPA_WITHOUT_SSR',
+      severity: 'warning',
+      category: 'crawlability',
+      title: `${analysis.frameworkDetected} detected without SSR markers`,
+      description:
+        `This appears to be a ${analysis.frameworkDetected} SPA without server-side rendering enabled.`,
+      impact:
+        'Single Page Applications without SSR have slower time-to-content for search crawlers.',
+      howToFix:
+        analysis.frameworkDetected === 'React'
+          ? 'Quick fix: Add react-snap (npm install -D react-snap) to pre-render at build time. Alternative: Use Vike for SSR/SSG.'
+          : 'Quick fix: Add prerender-spa-plugin to pre-render at build time. Alternative: Use Vike for SSR/SSG.',
+      affectedUrls: [url],
+      details: {
+        framework: analysis.frameworkDetected,
+        hasHydrationMarkers: analysis.hasHydrationMarkers,
+      },
+    });
+  }
+
+  // Notice: Static generation recommended
+  if (
+    analysis.renderingMethod === 'ssr' &&
+    analysis.confidence !== 'low'
+  ) {
+    // Not an issue, but we could suggest SSG for better performance
+    // This is informational only
+  }
+
+  // Warning: React/Vue without meta management library
+  if (
+    analysis.frameworkDetected &&
+    ['React', 'Vue'].includes(analysis.frameworkDetected) &&
+    !analysis.hasDynamicMetaTags &&
+    analysis.renderingMethod !== 'csr' // Don't double-warn for CSR
+  ) {
+    const helmetLib = analysis.frameworkDetected === 'React' ? 'React Helmet' : 'Vue Meta';
+    const metaTagsPresent = $('meta[name="description"], meta[property="og:title"]').length > 0;
+
+    if (!metaTagsPresent) {
+      issues.push({
+        code: 'SPA_NO_META_MANAGEMENT',
+        severity: 'warning',
+        category: 'on-page',
+        title: `${analysis.frameworkDetected} app may lack dynamic meta tag management`,
+        description:
+          `No ${helmetLib} or similar library detected for managing meta tags in this SPA.`,
+        impact:
+          'SPAs need dynamic meta tag management for proper page-specific titles, descriptions, and social tags.',
+        howToFix:
+          analysis.frameworkDetected === 'React'
+            ? 'Use React Helmet, Next.js Head, or Remix meta exports for dynamic meta tags.'
+            : 'Use Vue Meta, Nuxt Head, or vue-head for dynamic meta tags.',
+        affectedUrls: [url],
+        details: {
+          framework: analysis.frameworkDetected,
+          metaManagement: analysis.metaManagement,
+        },
+      });
+    }
+  }
+
+  // === AI-SPECIFIC CONTENT ACCESSIBILITY CHECKS ===
+
+  // Low AI readable score
+  if (analysis.aiAccessibility.aiReadableScore < 50) {
+    issues.push({
+      code: 'AI_LOW_HTML_READABILITY',
+      severity: 'warning',
+      category: 'ai-readiness',
+      title: 'Content not optimally accessible to AI systems',
+      description: `AI readability score: ${analysis.aiAccessibility.aiReadableScore}/100. AI systems like ChatGPT primarily read raw HTML and may miss JavaScript-rendered content.`,
+      impact: 'Content may not be properly indexed by AI search systems (ChatGPT, Perplexity, etc.), reducing AI citation likelihood.',
+      howToFix: 'Ensure key content is in the initial HTML response: 1) Use SSR/SSG, 2) Include title, H1, and main content in HTML, 3) Don\'t hide content behind JavaScript interactions.',
+      affectedUrls: [url],
+      details: {
+        aiReadableScore: analysis.aiAccessibility.aiReadableScore,
+        htmlContentRatio: analysis.aiAccessibility.htmlContentRatio,
+        hasSemanticStructure: analysis.aiAccessibility.hasSemanticStructure,
+        keyContentInHTML: analysis.aiAccessibility.keyContentInHTML,
+      },
+    });
+  }
+
+  // Missing semantic structure for AI
+  if (!analysis.aiAccessibility.hasSemanticStructure && analysis.mainContentCharCount > 500) {
+    issues.push({
+      code: 'AI_NO_SEMANTIC_STRUCTURE',
+      severity: 'notice',
+      category: 'ai-readiness',
+      title: 'Content lacks semantic HTML structure for AI parsing',
+      description: 'Missing semantic landmarks (<main>, <article>) or heading hierarchy. AI systems use these to identify and extract key content.',
+      impact: 'AI may not correctly identify the main content area, potentially extracting navigation or footer text instead.',
+      howToFix: 'Add semantic HTML: wrap main content in <main> or <article>, ensure H1 exists and heading hierarchy is logical (H1 → H2 → H3).',
+      affectedUrls: [url],
+    });
+  }
+
+  // Key content not in initial HTML
+  if (!analysis.aiAccessibility.keyContentInHTML && analysis.renderingMethod !== 'csr') {
+    issues.push({
+      code: 'AI_KEY_CONTENT_NOT_IN_HTML',
+      severity: 'warning',
+      category: 'ai-readiness',
+      title: 'Key content elements missing from initial HTML',
+      description: 'Title, H1, or opening paragraph content is missing or too short in the HTML. AI systems extract these first.',
+      impact: 'AI may not have access to your primary message, reducing chances of accurate citation.',
+      howToFix: 'Ensure the initial HTML contains: meaningful <title>, descriptive <h1>, and a substantial first paragraph with your key message.',
+      affectedUrls: [url],
+      details: {
+        hasTitle: $('title').text().trim().length > 10,
+        hasH1: $('h1').text().trim().length > 5,
+        hasFirstParagraph: $('p').first().text().trim().length > 50,
+      },
+    });
+  }
+
+  return { issues, data: analysis };
+}