@rankcli/agent-runtime 0.0.8 → 0.0.11

package/src/analyzers/index.ts

@@ -0,0 +1,233 @@
+/**
+ * RankCLI Analyzers
+ * 
+ * Industry-leading SEO analysis suite.
+ * Includes traditional SEO, Core Web Vitals, GEO (AI Search), and more.
+ */
+
+// GEO (Generative Engine Optimization) - AI Search
+export {
+  analyzeGEO,
+  analyzeRobotsTxtForAI,
+  detectRenderingMode,
+  analyzeContentStructure,
+  analyzeCitationReadiness,
+  analyzeEntityExtraction,
+  calculateLLMSignals,
+  generateAIFriendlyRobotsTxt,
+  AI_CRAWLERS_INFO,
+  type GEOAnalysisResult,
+  type AIAccessResult,
+  type ContentStructureResult,
+  type CitationResult,
+  type EntityResult,
+  type LLMSignalResult,
+} from './geo-analyzer.js';
+
+// Core Web Vitals
+export {
+  analyzeCoreWebVitals,
+  type CoreWebVitalsEstimate,
+} from './core-web-vitals-analyzer.js';
+
+// Security Headers
+export {
+  analyzeSecurityHeaders,
+  generateSecurityHeaders,
+  type SecurityHeadersResult,
+} from './security-headers-analyzer.js';
+
+// Structured Data / Schema.org
+export {
+  analyzeStructuredData,
+  generateSchemaTemplate,
+  type StructuredDataResult,
+  type SchemaItem,
+} from './structured-data-analyzer.js';
+
+// Image Optimization
+export {
+  analyzeImages,
+  generateResponsiveImage,
+  type ImageAnalysisResult,
+  type ImageInfo,
+} from './image-optimization-analyzer.js';
+
+// Internal Linking
+export {
+  analyzeInternalLinking,
+  suggestInternalLinks,
+  type InternalLinkingResult,
+  type LinkInfo,
+  type AnchorTextStats,
+} from './internal-linking-analyzer.js';
+
+// Mobile SEO
+export {
+  analyzeMobileSEO,
+  type MobileSEOResult,
+  type ViewportAnalysis,
+  type TouchTargetAnalysis,
+  type FontSizeAnalysis,
+  type ContentWidthAnalysis,
+  type MobileSpecificAnalysis,
+} from './mobile-seo-analyzer.js';
+
+/**
+ * Comprehensive SEO Analysis
+ * 
+ * Runs all analyzers and produces a unified report.
+ */
+export interface ComprehensiveSEOResult {
+  url: string;
+  timestamp: string;
+  overallScore: number;
+  grades: {
+    geo: number;
+    coreWebVitals: number;
+    security: string;
+    structuredData: number;
+    images: number;
+    internalLinking: number;
+    mobile: number;
+  };
+  geo: import('./geo-analyzer.js').GEOAnalysisResult;
+  coreWebVitals: import('./core-web-vitals-analyzer.js').CoreWebVitalsEstimate;
+  security: import('./security-headers-analyzer.js').SecurityHeadersResult;
+  structuredData: import('./structured-data-analyzer.js').StructuredDataResult;
+  images: import('./image-optimization-analyzer.js').ImageAnalysisResult;
+  internalLinking: import('./internal-linking-analyzer.js').InternalLinkingResult;
+  mobile: import('./mobile-seo-analyzer.js').MobileSEOResult;
+  allIssues: import('../audit/types.js').AuditIssue[];
+  prioritizedRecommendations: string[];
+}
+
+/**
+ * Run comprehensive SEO analysis
+ */
+export async function analyzeComprehensive(
+  html: string,
+  url: string,
+  options: {
+    robotsTxt?: string;
+    headers?: Record<string, string>;
+  } = {}
+): Promise<ComprehensiveSEOResult> {
+  const { robotsTxt, headers } = options;
+  
+  // Import analyzers
+  const { analyzeGEO } = await import('./geo-analyzer.js');
+  const { analyzeCoreWebVitals } = await import('./core-web-vitals-analyzer.js');
+  const { analyzeSecurityHeaders } = await import('./security-headers-analyzer.js');
+  const { analyzeStructuredData } = await import('./structured-data-analyzer.js');
+  const { analyzeImages } = await import('./image-optimization-analyzer.js');
+  const { analyzeInternalLinking } = await import('./internal-linking-analyzer.js');
+  const { analyzeMobileSEO } = await import('./mobile-seo-analyzer.js');
+  
+  // Run all analyzers
+  const geo = await analyzeGEO(html, url, robotsTxt);
+  const coreWebVitals = analyzeCoreWebVitals(html, url, headers);
+  const security = analyzeSecurityHeaders(headers || {}, url);
+  const structuredData = analyzeStructuredData(html, url);
+  const images = analyzeImages(html, url);
+  const internalLinking = analyzeInternalLinking(html, url);
+  const mobile = analyzeMobileSEO(html, url);
+  
+  // Collect all issues
+  const allIssues = [
+    ...geo.issues,
+    ...coreWebVitals.issues,
+    ...security.issues,
+    ...structuredData.issues,
+    ...images.issues,
+    ...internalLinking.issues,
+    ...mobile.issues,
+  ];
+  
+  // Sort by severity
+  const severityOrder: Record<string, number> = { critical: 0, error: 1, warning: 2, info: 3, notice: 4 };
+  allIssues.sort((a, b) => (severityOrder[a.severity] ?? 5) - (severityOrder[b.severity] ?? 5));
+  
+  // Calculate overall score (weighted average)
+  const weights = {
+    geo: 0.20,        // AI search is crucial
+    cwv: 0.20,        // Core Web Vitals
+    security: 0.10,   // Security headers
+    schema: 0.15,     // Structured data
+    images: 0.10,     // Image optimization
+    links: 0.10,      // Internal linking
+    mobile: 0.15,     // Mobile SEO
+  };
+  
+  const securityScore = 
+    security.grade === 'A+' ? 100 :
+    security.grade === 'A' ? 90 :
+    security.grade === 'B' ? 75 :
+    security.grade === 'C' ? 55 :
+    security.grade === 'D' ? 35 : 20;
+  
+  const overallScore = Math.round(
+    (geo.score * weights.geo) +
+    (coreWebVitals.overallScore * weights.cwv) +
+    (securityScore * weights.security) +
+    (structuredData.score * weights.schema) +
+    (images.score * weights.images) +
+    (internalLinking.score * weights.links) +
+    (mobile.score * weights.mobile)
+  );
+  
+  // Prioritize recommendations
+  const prioritizedRecommendations: string[] = [];
+  
+  // Critical GEO issues first
+  if (geo.aiCrawlerAccess.blockedCrawlers.length > 0) {
+    prioritizedRecommendations.push('🚨 URGENT: Unblock AI crawlers (GPTBot, PerplexityBot) in robots.txt');
+  }
+  if (geo.aiCrawlerAccess.jsRenderingRequired && !geo.aiCrawlerAccess.hasPrerendering) {
+    prioritizedRecommendations.push('🚨 URGENT: Implement SSR - AI crawlers cannot see your JS-rendered content');
+  }
+  
+  // CWV critical issues
+  const criticalCWV = coreWebVitals.issues.filter(i => i.severity === 'critical');
+  criticalCWV.forEach(i => prioritizedRecommendations.push(`⚡ ${i.title}`));
+  
+  // Security critical
+  if (!security.https.enabled) {
+    prioritizedRecommendations.push('🔒 Enable HTTPS immediately');
+  }
+  
+  // Mobile critical
+  if (!mobile.viewport.hasViewport) {
+    prioritizedRecommendations.push('📱 Add viewport meta tag for mobile rendering');
+  }
+  
+  // Add top recommendations from each analyzer
+  geo.recommendations.slice(0, 2).forEach(r => prioritizedRecommendations.push(r));
+  structuredData.recommendations.slice(0, 2).forEach(r => prioritizedRecommendations.push(r));
+  images.recommendations.slice(0, 2).forEach(r => prioritizedRecommendations.push(r));
+  internalLinking.recommendations.slice(0, 2).forEach(r => prioritizedRecommendations.push(r));
+  
+  return {
+    url,
+    timestamp: new Date().toISOString(),
+    overallScore,
+    grades: {
+      geo: geo.score,
+      coreWebVitals: coreWebVitals.overallScore,
+      security: security.grade,
+      structuredData: structuredData.score,
+      images: images.score,
+      internalLinking: internalLinking.score,
+      mobile: mobile.score,
+    },
+    geo,
+    coreWebVitals,
+    security,
+    structuredData,
+    images,
+    internalLinking,
+    mobile,
+    allIssues,
+    prioritizedRecommendations,
+  };
+}

package/src/analyzers/internal-linking-analyzer.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeInternalLinking, suggestInternalLinks } from './internal-linking-analyzer.js';
+
+describe('Internal Linking Analyzer', () => {
+  describe('analyzeInternalLinking', () => {
+    it('counts internal and external links', () => {
+      const html = `
+<html><body>
+  <a href="/about">About</a>
+  <a href="/products">Products</a>
+  <a href="https://external.com">External</a>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com/page');
+      expect(result.internalLinks).toBe(2);
+      expect(result.externalLinks).toBe(1);
+      expect(result.totalLinks).toBe(3);
+    });
+
+    it('distinguishes navigation from content links', () => {
+      const html = `
+<html><body>
+  <nav>
+    <a href="/home">Home</a>
+    <a href="/about">About</a>
+  </nav>
+  <main>
+    <a href="/products">See our products</a>
+  </main>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com');
+      expect(result.navigationLinks).toBe(2);
+      expect(result.contentLinks).toBe(1);
+    });
+
+    it('detects generic anchor text', () => {
+      const html = `
+<html><body>
+  <a href="/about">Click here</a>
+  <a href="/products">Read more</a>
+  <a href="/services">Learn more</a>
+  <a href="/contact">here</a>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com');
+      expect(result.linksWithGenericText).toBe(4);
+      expect(result.issues.some(i => i.code === 'LINK_GENERIC_ANCHOR')).toBe(true);
+    });
+
+    it('detects descriptive anchor text', () => {
+      const html = `
+<html><body>
+  <a href="/about">About Our Company</a>
+  <a href="/products">Our Product Catalog</a>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com');
+      expect(result.linksWithKeywords).toBe(2);
+    });
+
+    it('detects empty anchor text', () => {
+      const html = `
+<html><body>
+  <a href="/about"></a>
+  <a href="/products">   </a>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com');
+      expect(result.anchorTextAnalysis.empty).toBe(2);
+      expect(result.issues.some(i => i.code === 'LINK_EMPTY_ANCHOR')).toBe(true);
+    });
+
+    it('detects nofollow on internal links', () => {
+      const html = `
+<html><body>
+  <a href="/about" rel="nofollow">About</a>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com');
+      expect(result.issues.some(i => i.code === 'LINK_NOFOLLOW_INTERNAL')).toBe(true);
+    });
+
+    it('tracks unique internal targets', () => {
+      const html = `
+<html><body>
+  <a href="/about">About</a>
+  <a href="/about">About Us</a>
+  <a href="/products">Products</a>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com');
+      expect(result.uniqueInternalTargets).toBe(2);
+    });
+
+    it('detects orphan risk', () => {
+      const html = `
+<html><body>
+  <nav><a href="/home">Home</a></nav>
+  <p>Content without links</p>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com/orphan');
+      expect(result.orphanRisk).toBe(true);
+    });
+
+    it('handles image links', () => {
+      const html = `
+<html><body>
+  <a href="/products"><img src="/logo.png" alt="Products"></a>
+  <a href="/about"><img src="/icon.png"></a>
+</body></html>
+`;
+      const result = analyzeInternalLinking(html, 'https://example.com');
+      expect(result.anchorTextAnalysis.imageLinks).toBe(2);
+    });
+  });
+
+  describe('suggestInternalLinks', () => {
+    it('suggests links based on keyword matches', () => {
+      const content = '<p>Learn about SEO optimization techniques.</p>';
+      const pages = [
+        { url: '/seo-guide', title: 'SEO Guide', keywords: ['seo', 'optimization'] },
+        { url: '/about', title: 'About', keywords: ['company', 'team'] },
+      ];
+      
+      const suggestions = suggestInternalLinks(content, pages);
+      expect(suggestions.some(s => s.suggestedUrl === '/seo-guide')).toBe(true);
+    });
+
+    it('does not suggest already linked pages', () => {
+      const content = '<p>Learn about SEO optimization. <a href="/seo-guide">Guide</a></p>';
+      const pages = [
+        { url: '/seo-guide', title: 'SEO Guide', keywords: ['seo'] },
+      ];
+      
+      const suggestions = suggestInternalLinks(content, pages);
+      expect(suggestions.length).toBe(0);
+    });
+  });
+});