@rankcli/agent-runtime 0.0.14 → 0.0.16

package/src/audit/checks/brand-mention-optimization.ts

@@ -1,349 +0,0 @@
-/**
- * Brand Mention Optimization Checks
- *
- * AI systems extract and quote brand information when answering queries.
- * This check analyzes whether your brand is clearly defined in a way
- * that AI can extract, quote, and recommend.
- *
- * Key insight: "AI doesn't decide who you are. It mostly just repeats
- * what it finds on the internet." - Control your brand narrative.
- */
-
-import * as cheerio from 'cheerio';
-import type { AuditIssue } from '../types.js';
-
-export interface BrandMentionData {
-  brandSignals: {
-    hasBrandDefinition: boolean;
-    hasUSP: boolean;
-    hasValueProposition: boolean;
-    hasBrandStatement: boolean;
-    brandMentionCount: number;
-  };
-  brandCoverage: {
-    hasPricingInfo: boolean;
-    hasAboutSection: boolean;
-    hasFAQSection: boolean;
-    hasTestimonials: boolean;
-    hasProofPoints: boolean;
-  };
-  brandConsistency: {
-    hasConsistentNaming: boolean;
-    hasContactInfo: boolean;
-    hasSocialLinks: boolean;
-    hasReviewLinks: boolean;
-  };
-  quotableBrandStatements: string[];
-  brandScore: number;
-}
-
-// Patterns for brand-defining statements
-const BRAND_DEFINITION_PATTERNS = [
-  /(?:we are|we're|is a|is the|is an)\s+(?:leading|premier|top|best|trusted|innovative|professional)/i,
-  /(?:our mission|our vision|we help|we provide|we offer|we specialize)/i,
-  /(?:founded in|established in|since \d{4}|for over \d+)/i,
-];
-
-// USP (Unique Selling Proposition) patterns
-const USP_PATTERNS = [
-  /(?:only|unique|exclusive|proprietary|patented|first|original)/i,
-  /(?:unlike|different from|better than|compared to)/i,
-  /(?:guarantee|warranty|promise|commitment)/i,
-  /(?:free|no cost|complimentary|included)/i,
-  /(?:\d+%|\d+x|\d+ times|faster|cheaper|easier)/i,
-];
-
-// Value proposition patterns
-const VALUE_PROP_PATTERNS = [
-  /(?:save|reduce|increase|improve|boost|grow|maximize|minimize)/i,
-  /(?:get|achieve|reach|attain|unlock|discover)/i,
-  /(?:without|no need|don't have to|eliminates|removes)/i,
-];
-
-// Review platform domains
-const REVIEW_PLATFORMS = [
-  'trustpilot.com', 'g2.com', 'capterra.com', 'yelp.com',
-  'bbb.org', 'glassdoor.com', 'indeed.com', 'tripadvisor.com',
-  'angi.com', 'homeadvisor.com', 'avvo.com', 'healthgrades.com',
-  'zocdoc.com', 'clutch.co', 'producthunt.com', 'getapp.com',
-];
-
-export function analyzeBrandMentionOptimization(
-  html: string,
-  url: string
-): { issues: AuditIssue[]; data: BrandMentionData } {
-  const issues: AuditIssue[] = [];
-  const $ = cheerio.load(html);
-  const parsedUrl = new URL(url);
-
-  // Remove non-content elements
-  const $content = $('body').clone();
-  $content.find('nav, footer, script, style, noscript').remove();
-  const bodyText = $content.text();
-  const bodyHtml = $content.html() || '';
-
-  // Extract potential brand name from domain or title
-  const domainParts = parsedUrl.hostname.replace('www.', '').split('.');
-  const potentialBrandName = domainParts[0];
-  const title = $('title').text();
-  const ogSiteName = $('meta[property="og:site_name"]').attr('content') || '';
-
-  // Count brand mentions
-  const brandNameRegex = new RegExp(potentialBrandName, 'gi');
-  const brandMentionCount = (bodyText.match(brandNameRegex) || []).length;
-
-  // Check for brand definition patterns
-  let hasBrandDefinition = false;
-  let hasUSP = false;
-  let hasValueProposition = false;
-  let hasBrandStatement = false;
-  const quotableBrandStatements: string[] = [];
-
-  // Analyze paragraphs for brand statements
-  $content.find('p, li, h1, h2, h3').each((_, el) => {
-    const text = $(el).text().trim();
-    if (text.length < 20 || text.length > 300) return;
-
-    // Check for brand definitions
-    for (const pattern of BRAND_DEFINITION_PATTERNS) {
-      if (pattern.test(text)) {
-        hasBrandDefinition = true;
-        if (text.length <= 200 && quotableBrandStatements.length < 5) {
-          quotableBrandStatements.push(text);
-        }
-        break;
-      }
-    }
-
-    // Check for USPs
-    for (const pattern of USP_PATTERNS) {
-      if (pattern.test(text)) {
-        hasUSP = true;
-        break;
-      }
-    }
-
-    // Check for value propositions
-    for (const pattern of VALUE_PROP_PATTERNS) {
-      if (pattern.test(text)) {
-        hasValueProposition = true;
-        break;
-      }
-    }
-  });
-
-  // Check for explicit brand statement (often in hero or about section)
-  hasBrandStatement =
-    $('[class*="hero"] p, [class*="about"] p, [id*="hero"] p, [id*="about"] p').length > 0 ||
-    $('main > section:first-child p').length > 0;
-
-  // Check brand topic coverage
-  const headingText = $('h1, h2, h3, h4').map((_, h) => $(h).text().toLowerCase()).get().join(' ');
-  const linkText = $('a').map((_, a) => $(a).text().toLowerCase()).get().join(' ');
-  const allLinks = $('a[href]').map((_, a) => $(a).attr('href') || '').get();
-
-  const hasPricingInfo =
-    headingText.includes('pricing') ||
-    headingText.includes('plans') ||
-    headingText.includes('cost') ||
-    linkText.includes('pricing') ||
-    allLinks.some(href => href.includes('pricing') || href.includes('plans'));
-
-  const hasAboutSection =
-    headingText.includes('about') ||
-    headingText.includes('who we are') ||
-    headingText.includes('our story') ||
-    allLinks.some(href => href.includes('about'));
-
-  const hasFAQSection =
-    headingText.includes('faq') ||
-    headingText.includes('frequently asked') ||
-    headingText.includes('questions') ||
-    $('[itemtype*="FAQPage"]').length > 0 ||
-    $('details summary').length >= 2;
-
-  const hasTestimonials =
-    headingText.includes('testimonial') ||
-    headingText.includes('review') ||
-    headingText.includes('what our') ||
-    headingText.includes('customer') ||
-    $('[class*="testimonial"], [class*="review"], [id*="testimonial"]').length > 0 ||
-    $('blockquote').length >= 2;
-
-  const hasProofPoints =
-    headingText.includes('case stud') ||
-    headingText.includes('success') ||
-    headingText.includes('results') ||
-    /\d+\+?\s*(customers|clients|users|companies|businesses)/i.test(bodyText) ||
-    /\d+%\s*(increase|decrease|improvement|growth)/i.test(bodyText);
-
-  // Check brand consistency signals
-  const hasConsistentNaming = brandMentionCount >= 3 && ogSiteName.length > 0;
-
-  const hasContactInfo =
-    $('a[href^="tel:"], a[href^="mailto:"]').length > 0 ||
-    /\d{3}[-.\s]?\d{3}[-.\s]?\d{4}/.test(bodyText) ||
-    bodyText.toLowerCase().includes('contact');
-
-  const socialLinks = $('a[href*="facebook.com"], a[href*="twitter.com"], a[href*="linkedin.com"], a[href*="instagram.com"]');
-  const hasSocialLinks = socialLinks.length >= 2;
-
-  // Check for review platform links
-  const hasReviewLinks = allLinks.some(href => {
-    const lowerHref = href.toLowerCase();
-    return REVIEW_PLATFORMS.some(platform => lowerHref.includes(platform));
-  });
-
-  // Calculate brand score
-  let brandScore = 30; // Base score
-
-  // Brand signals
-  if (hasBrandDefinition) brandScore += 15;
-  if (hasUSP) brandScore += 10;
-  if (hasValueProposition) brandScore += 10;
-  if (brandMentionCount >= 5) brandScore += 5;
-
-  // Brand coverage
-  if (hasPricingInfo) brandScore += 5;
-  if (hasAboutSection) brandScore += 5;
-  if (hasFAQSection) brandScore += 5;
-  if (hasTestimonials) brandScore += 10;
-  if (hasProofPoints) brandScore += 10;
-
-  // Brand consistency
-  if (hasConsistentNaming) brandScore += 5;
-  if (hasContactInfo) brandScore += 3;
-  if (hasSocialLinks) brandScore += 3;
-  if (hasReviewLinks) brandScore += 5;
-
-  brandScore = Math.min(100, Math.max(0, brandScore));
-
-  // Generate issues
-
-  // No clear brand definition
-  if (!hasBrandDefinition) {
-    issues.push({
-      code: 'AI_NO_BRAND_DEFINITION',
-      severity: 'warning',
-      category: 'ai-readiness',
-      title: 'No clear brand definition for AI to extract',
-      description: 'AI systems look for clear "Brand X is..." statements to quote when recommending brands. Your page lacks quotable brand definitions.',
-      impact: 'AI cannot accurately describe your brand, reducing recommendation likelihood.',
-      howToFix: 'Add a clear brand definition early in your content: "[Brand] is a [category] that [key benefit]." Make it quotable (under 200 characters).',
-      affectedUrls: [url],
-      details: {
-        suggestion: `Example: "${potentialBrandName.charAt(0).toUpperCase() + potentialBrandName.slice(1)} is a [category] that helps [audience] [achieve benefit]."`,
-      },
-    });
-  }
-
-  // No USP
-  if (!hasUSP) {
-    issues.push({
-      code: 'AI_NO_USP',
-      severity: 'notice',
-      category: 'ai-readiness',
-      title: 'No unique selling proposition (USP) detected',
-      description: 'AI needs clear differentiators to recommend your brand over competitors. No USP patterns found.',
-      impact: 'AI may not distinguish your brand from competitors when making recommendations.',
-      howToFix: 'Add clear differentiators: "The only...", "Unlike competitors...", "Guaranteed...", specific numbers (e.g., "50% faster").',
-      affectedUrls: [url],
-    });
-  }
-
-  // Missing brand topic coverage
-  const missingTopics: string[] = [];
-  if (!hasPricingInfo) missingTopics.push('pricing');
-  if (!hasFAQSection) missingTopics.push('FAQ');
-  if (!hasTestimonials) missingTopics.push('testimonials/reviews');
-  if (!hasProofPoints) missingTopics.push('proof points/case studies');
-
-  if (missingTopics.length >= 2) {
-    issues.push({
-      code: 'AI_INCOMPLETE_BRAND_COVERAGE',
-      severity: 'notice',
-      category: 'ai-readiness',
-      title: 'Incomplete brand topic coverage',
-      description: `Missing key brand topics that AI uses to answer queries: ${missingTopics.join(', ')}. AI may rely on third-party sources instead.`,
-      impact: 'Third-party sites may define your brand narrative instead of you.',
-      howToFix: 'Cover key brand topics on your site: pricing, positioning, proof (testimonials, case studies), and FAQs.',
-      affectedUrls: [url],
-      details: {
-        missingTopics,
-        recommendation: 'Control your brand narrative by having authoritative content on these topics on your own site.',
-      },
-    });
-  }
-
-  // No review platform integration
-  if (!hasReviewLinks && !hasTestimonials) {
-    issues.push({
-      code: 'AI_NO_REVIEW_INTEGRATION',
-      severity: 'notice',
-      category: 'ai-readiness',
-      title: 'No review platform integration',
-      description: 'No links to review platforms or testimonial sections found. AI uses review signals from multiple platforms for trust.',
-      impact: 'Missing review diversity signals that AI uses for brand trust assessment.',
-      howToFix: 'Link to your profiles on relevant review platforms (G2, Capterra, Trustpilot, etc.) and display testimonials with attribution.',
-      affectedUrls: [url],
-      details: {
-        relevantPlatforms: [
-          'B2B SaaS: G2, Capterra, TrustRadius',
-          'Local: Google Business, Yelp, BBB',
-          'Professional: Clutch, UpCity',
-        ],
-      },
-    });
-  }
-
-  // Low brand score
-  if (brandScore < 50) {
-    issues.push({
-      code: 'AI_LOW_BRAND_SCORE',
-      severity: 'warning',
-      category: 'ai-readiness',
-      title: 'Brand is not well-optimized for AI extraction',
-      description: `Brand optimization score: ${brandScore}/100. AI may struggle to accurately describe and recommend your brand.`,
-      impact: 'Low likelihood of being recommended in AI answers for brand-related queries.',
-      howToFix: 'Improve brand clarity: add quotable definitions, USPs, testimonials, proof points, and link to review platforms.',
-      affectedUrls: [url],
-      details: {
-        brandScore,
-        hasBrandDefinition,
-        hasUSP,
-        hasTestimonials,
-        hasProofPoints,
-        hasReviewLinks,
-        quotableBrandStatements: quotableBrandStatements.slice(0, 3),
-      },
-    });
-  }
-
-  return {
-    issues,
-    data: {
-      brandSignals: {
-        hasBrandDefinition,
-        hasUSP,
-        hasValueProposition,
-        hasBrandStatement,
-        brandMentionCount,
-      },
-      brandCoverage: {
-        hasPricingInfo,
-        hasAboutSection,
-        hasFAQSection,
-        hasTestimonials,
-        hasProofPoints,
-      },
-      brandConsistency: {
-        hasConsistentNaming,
-        hasContactInfo,
-        hasSocialLinks,
-        hasReviewLinks,
-      },
-      quotableBrandStatements,
-      brandScore,
-    },
-  };
-}

package/src/audit/checks/caching-headers.ts

@@ -1,305 +0,0 @@
-/**
- * Browser Caching Headers Check
- *
- * Validates HTTP caching headers for optimal performance:
- * - Cache-Control header
- * - Expires header
- * - ETag header
- * - Last-Modified header
- *
- * Proper caching improves page load times for repeat visitors
- * and reduces server load.
- */
-
-import { httpGet } from '../../utils/http.js';
-import type { AuditIssue } from '../types.js';
-
-export interface CachingHeadersData {
-  htmlCaching: {
-    cacheControl?: string;
-    expires?: string;
-    etag?: string;
-    lastModified?: string;
-    maxAge?: number;
-    isPublic: boolean;
-    isPrivate: boolean;
-    noStore: boolean;
-    noCache: boolean;
-  };
-  staticAssets: AssetCachingInfo[];
-  issues: {
-    noCaching: number;
-    shortTtl: number;
-    properlyConfigured: number;
-  };
-}
-
-interface AssetCachingInfo {
-  url: string;
-  type: string;
-  cacheControl?: string;
-  maxAge?: number;
-  hasCaching: boolean;
-}
-
-// Recommended cache durations (in seconds)
-const CACHE_RECOMMENDATIONS = {
-  html: 0, // HTML should generally not be cached or have short TTL
-  css: 31536000, // 1 year for versioned assets
-  js: 31536000,
-  images: 31536000,
-  fonts: 31536000,
-  minimum: 86400, // 1 day minimum for static assets
-};
-
-export async function analyzeCachingHeaders(
-  url: string,
-  headers?: Record<string, string>
-): Promise<{ issues: AuditIssue[]; data: CachingHeadersData }> {
-  const issues: AuditIssue[] = [];
-
-  // Analyze HTML page headers
-  let htmlHeaders = headers;
-  if (!htmlHeaders) {
-    try {
-      const response = await httpGet<string>(url, {
-        timeout: 10000,
-        validateStatus: () => true,
-      });
-      htmlHeaders = response.headers as Record<string, string>;
-    } catch {
-      htmlHeaders = {};
-    }
-  }
-
-  const htmlCaching = parseCacheHeaders(htmlHeaders);
-
-  // Check HTML caching (should be minimal or no caching)
-  if (htmlCaching.maxAge && htmlCaching.maxAge > 3600) {
-    issues.push({
-      code: 'CACHING_HTML_TOO_LONG',
-      severity: 'notice',
-      category: 'performance',
-      title: 'HTML page has long cache duration',
-      description: `HTML page has Cache-Control max-age of ${htmlCaching.maxAge} seconds (${Math.round(htmlCaching.maxAge / 3600)} hours). HTML content changes frequently.`,
-      impact: 'Users may see stale content. Content updates may not appear immediately.',
-      howToFix: 'Set shorter cache duration for HTML: Cache-Control: no-cache or max-age=0, must-revalidate',
-      affectedUrls: [url],
-    });
-  }
-
-  // Sample static assets to check their caching
-  const staticAssets: AssetCachingInfo[] = [];
-  const assetUrls = await getStaticAssetUrls(url);
-
-  let noCaching = 0;
-  let shortTtl = 0;
-  let properlyConfigured = 0;
-
-  // Check up to 5 static assets
-  const assetsToCheck = assetUrls.slice(0, 5);
-
-  for (const assetUrl of assetsToCheck) {
-    try {
-      const assetResponse = await httpGet<string>(assetUrl, {
-        timeout: 5000,
-        validateStatus: () => true,
-      });
-
-      const assetCaching = parseCacheHeaders(assetResponse.headers as Record<string, string>);
-      const type = getAssetType(assetUrl);
-
-      const assetInfo: AssetCachingInfo = {
-        url: assetUrl,
-        type,
-        cacheControl: assetCaching.cacheControl,
-        maxAge: assetCaching.maxAge,
-        hasCaching: Boolean(assetCaching.cacheControl || assetCaching.expires),
-      };
-
-      staticAssets.push(assetInfo);
-
-      if (!assetInfo.hasCaching) {
-        noCaching++;
-      } else if (assetCaching.maxAge && assetCaching.maxAge < CACHE_RECOMMENDATIONS.minimum) {
-        shortTtl++;
-      } else {
-        properlyConfigured++;
-      }
-    } catch {
-      // Asset check failed, skip
-    }
-  }
-
-  // Generate issues for static assets
-  if (noCaching > 0) {
-    issues.push({
-      code: 'CACHING_STATIC_NO_CACHE',
-      severity: 'warning',
-      category: 'performance',
-      title: 'Static assets missing cache headers',
-      description: `${noCaching} static asset(s) have no Cache-Control header. This forces browsers to re-download on every visit.`,
-      impact: 'Slower page loads for repeat visitors. Increased bandwidth usage.',
-      howToFix: 'Add Cache-Control headers to static assets. For versioned files (with hash in filename), use: Cache-Control: public, max-age=31536000, immutable',
-      affectedUrls: staticAssets.filter(a => !a.hasCaching).map(a => a.url),
-      details: {
-        recommendation: {
-          'versioned assets (with hash)': 'Cache-Control: public, max-age=31536000, immutable',
-          'non-versioned assets': 'Cache-Control: public, max-age=86400',
-        },
-      },
-    });
-  }
-
-  if (shortTtl > 0) {
-    issues.push({
-      code: 'CACHING_STATIC_SHORT_TTL',
-      severity: 'notice',
-      category: 'performance',
-      title: 'Static assets have short cache duration',
-      description: `${shortTtl} static asset(s) have cache duration under 1 day. Consider longer caching for better performance.`,
-      impact: 'Assets are re-downloaded more often than necessary.',
-      howToFix: 'Increase max-age for static assets. Use versioned filenames (hash in filename) to enable long-term caching.',
-      affectedUrls: staticAssets.filter(a => a.maxAge && a.maxAge < CACHE_RECOMMENDATIONS.minimum).map(a => a.url),
-    });
-  }
-
-  // Check for missing ETag or Last-Modified
-  if (!htmlCaching.etag && !htmlCaching.lastModified) {
-    issues.push({
-      code: 'CACHING_NO_VALIDATORS',
-      severity: 'notice',
-      category: 'performance',
-      title: 'Missing cache validators (ETag/Last-Modified)',
-      description: 'Page is missing both ETag and Last-Modified headers. These allow efficient cache validation.',
-      impact: 'Browsers cannot efficiently validate if cached content is still fresh.',
-      howToFix: 'Configure your server to send ETag or Last-Modified headers. Most web servers do this automatically for static files.',
-      affectedUrls: [url],
-    });
-  }
-
-  return {
-    issues,
-    data: {
-      htmlCaching,
-      staticAssets,
-      issues: {
-        noCaching,
-        shortTtl,
-        properlyConfigured,
-      },
-    },
-  };
-}
-
-function parseCacheHeaders(headers: Record<string, string>): CachingHeadersData['htmlCaching'] {
-  const cacheControl = headers['cache-control'] || headers['Cache-Control'];
-  const expires = headers['expires'] || headers['Expires'];
-  const etag = headers['etag'] || headers['ETag'];
-  const lastModified = headers['last-modified'] || headers['Last-Modified'];
-
-  let maxAge: number | undefined;
-  let isPublic = false;
-  let isPrivate = false;
-  let noStore = false;
-  let noCache = false;
-
-  if (cacheControl) {
-    // Parse max-age
-    const maxAgeMatch = cacheControl.match(/max-age=(\d+)/i);
-    if (maxAgeMatch) {
-      maxAge = parseInt(maxAgeMatch[1], 10);
-    }
-
-    // Parse directives
-    const lowerCC = cacheControl.toLowerCase();
-    isPublic = lowerCC.includes('public');
-    isPrivate = lowerCC.includes('private');
-    noStore = lowerCC.includes('no-store');
-    noCache = lowerCC.includes('no-cache');
-  }
-
-  return {
-    cacheControl,
-    expires,
-    etag,
-    lastModified,
-    maxAge,
-    isPublic,
-    isPrivate,
-    noStore,
-    noCache,
-  };
-}
-
-async function getStaticAssetUrls(pageUrl: string): Promise<string[]> {
-  const assets: string[] = [];
-
-  try {
-    const response = await httpGet<string>(pageUrl, {
-      timeout: 10000,
-      validateStatus: () => true,
-    });
-
-    const html = response.data as string;
-    const baseUrl = new URL(pageUrl);
-
-    // Extract CSS files
-    const cssMatches = html.match(/href="([^"]+\.css[^"]*)"/gi);
-    if (cssMatches) {
-      for (const match of cssMatches.slice(0, 2)) {
-        const href = match.match(/href="([^"]+)"/)?.[1];
-        if (href) {
-          try {
-            assets.push(new URL(href, baseUrl).href);
-          } catch {
-            // Invalid URL
-          }
-        }
-      }
-    }
-
-    // Extract JS files
-    const jsMatches = html.match(/src="([^"]+\.js[^"]*)"/gi);
-    if (jsMatches) {
-      for (const match of jsMatches.slice(0, 2)) {
-        const src = match.match(/src="([^"]+)"/)?.[1];
-        if (src) {
-          try {
-            assets.push(new URL(src, baseUrl).href);
-          } catch {
-            // Invalid URL
-          }
-        }
-      }
-    }
-
-    // Extract image files
-    const imgMatches = html.match(/src="([^"]+\.(png|jpg|jpeg|gif|webp|svg)[^"]*)"/gi);
-    if (imgMatches) {
-      for (const match of imgMatches.slice(0, 1)) {
-        const src = match.match(/src="([^"]+)"/)?.[1];
-        if (src) {
-          try {
-            assets.push(new URL(src, baseUrl).href);
-          } catch {
-            // Invalid URL
-          }
-        }
-      }
-    }
-  } catch {
-    // Failed to fetch page
-  }
-
-  return assets;
-}
-
-function getAssetType(url: string): string {
-  const lowerUrl = url.toLowerCase();
-  if (lowerUrl.includes('.css')) return 'css';
-  if (lowerUrl.includes('.js')) return 'javascript';
-  if (lowerUrl.match(/\.(png|jpg|jpeg|gif|webp|svg|ico)/)) return 'image';
-  if (lowerUrl.match(/\.(woff|woff2|ttf|otf|eot)/)) return 'font';
-  return 'other';
-}