@rankcli/agent-runtime 0.0.15 → 0.0.17

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

@@ -1,419 +0,0 @@
-/**
- * Internal Linking Analyzer
- * 
- * Analyzes internal link structure for SEO optimization.
- * Checks link distribution, anchor text, orphan pages, and link depth.
- */
-
-import * as cheerio from 'cheerio';
-import type { AuditIssue } from '../audit/types.js';
-
-export interface InternalLinkingResult {
-  score: number;
-  totalLinks: number;
-  internalLinks: number;
-  externalLinks: number;
-  navigationLinks: number;
-  contentLinks: number;
-  uniqueInternalTargets: number;
-  linksWithKeywords: number;
-  linksWithGenericText: number;
-  orphanRisk: boolean;
-  linkDetails: LinkInfo[];
-  anchorTextAnalysis: AnchorTextStats;
-  issues: AuditIssue[];
-  recommendations: string[];
-}
-
-export interface LinkInfo {
-  href: string;
-  text: string;
-  isInternal: boolean;
-  isNavigation: boolean;
-  rel?: string;
-  title?: string;
-  issues: string[];
-}
-
-export interface AnchorTextStats {
-  total: number;
-  descriptive: number;
-  generic: number;
-  empty: number;
-  tooLong: number;
-  imageLinks: number;
-  patterns: { text: string; count: number }[];
-}
-
-const GENERIC_ANCHOR_TEXTS = [
-  'click here',
-  'read more',
-  'learn more',
-  'here',
-  'link',
-  'this',
-  'more',
-  'continue',
-  'see more',
-  'view more',
-  'details',
-  'go',
-  'continue reading',
-  '>>',
-  '→',
-  'next',
-  'previous',
-];
-
-/**
- * Check if URL is internal
- */
-function isInternalUrl(href: string, baseUrl: string): boolean {
-  if (!href || href.startsWith('#') || href.startsWith('javascript:') || href.startsWith('mailto:') || href.startsWith('tel:')) {
-    return false;
-  }
-  
-  if (href.startsWith('/') && !href.startsWith('//')) {
-    return true;
-  }
-  
-  try {
-    const base = new URL(baseUrl);
-    const link = new URL(href, baseUrl);
-    return link.hostname === base.hostname;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if link is in navigation
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function isNavigationLink($el: cheerio.Cheerio<any>, $: cheerio.CheerioAPI): boolean {
-  const parent = $el.parents('nav, header, footer, [role="navigation"], .nav, .navigation, .menu, .sidebar').first();
-  return parent.length > 0;
-}
-
-/**
- * Analyze anchor text quality
- */
-function analyzeAnchorText(text: string): { isGeneric: boolean; isTooLong: boolean; isEmpty: boolean } {
-  const normalized = text.toLowerCase().trim();
-  
-  return {
-    isEmpty: normalized.length === 0,
-    isGeneric: GENERIC_ANCHOR_TEXTS.some(g => normalized === g || normalized.includes(g)),
-    isTooLong: normalized.length > 100,
-  };
-}
-
-/**
- * Analyze internal linking structure
- */
-export function analyzeInternalLinking(html: string, url: string): InternalLinkingResult {
-  const $ = cheerio.load(html);
-  const issues: AuditIssue[] = [];
-  const recommendations: string[] = [];
-  let score = 100;
-  
-  const linkDetails: LinkInfo[] = [];
-  const anchorTextCounts: Record<string, number> = {};
-  
-  let totalLinks = 0;
-  let internalLinks = 0;
-  let externalLinks = 0;
-  let navigationLinks = 0;
-  let contentLinks = 0;
-  let linksWithGenericText = 0;
-  let linksWithKeywords = 0;
-  let emptyAnchorLinks = 0;
-  let tooLongAnchorLinks = 0;
-  let imageLinks = 0;
-  
-  const internalTargets = new Set<string>();
-  
-  $('a[href]').each((_, el) => {
-    const $link = $(el);
-    const href = $link.attr('href') || '';
-    const text = $link.text().trim();
-    const rel = $link.attr('rel');
-    const title = $link.attr('title');
-    const hasImage = $link.find('img').length > 0;
-    
-    // Skip non-HTTP links
-    if (href.startsWith('mailto:') || href.startsWith('tel:') || href.startsWith('javascript:')) {
-      return;
-    }
-    
-    totalLinks++;
-    const linkIssues: string[] = [];
-    const isInternal = isInternalUrl(href, url);
-    const isNav = isNavigationLink($link, $);
-    
-    if (isInternal) {
-      internalLinks++;
-      
-      // Track unique targets
-      try {
-        const targetUrl = new URL(href, url).pathname;
-        internalTargets.add(targetUrl);
-      } catch {}
-    } else if (href.startsWith('http')) {
-      externalLinks++;
-    }
-    
-    if (isNav) {
-      navigationLinks++;
-    } else {
-      contentLinks++;
-    }
-    
-    // Analyze anchor text
-    const anchorAnalysis = analyzeAnchorText(text);
-    
-    if (hasImage && !text) {
-      imageLinks++;
-      const imgAlt = $link.find('img').attr('alt');
-      if (!imgAlt) {
-        linkIssues.push('Image link without alt text');
-      }
-    } else if (anchorAnalysis.isEmpty) {
-      emptyAnchorLinks++;
-      linkIssues.push('Empty anchor text');
-    } else if (anchorAnalysis.isGeneric) {
-      linksWithGenericText++;
-      linkIssues.push('Generic anchor text');
-    } else {
-      linksWithKeywords++;
-    }
-    
-    if (anchorAnalysis.isTooLong) {
-      tooLongAnchorLinks++;
-      linkIssues.push('Anchor text too long');
-    }
-    
-    // Track anchor text patterns
-    if (text) {
-      const normalizedText = text.toLowerCase().substring(0, 50);
-      anchorTextCounts[normalizedText] = (anchorTextCounts[normalizedText] || 0) + 1;
-    }
-    
-    // Check for nofollow on internal links
-    if (isInternal && rel?.includes('nofollow')) {
-      linkIssues.push('nofollow on internal link');
-    }
-    
-    // Check for sponsored/ugc on internal links
-    if (isInternal && (rel?.includes('sponsored') || rel?.includes('ugc'))) {
-      linkIssues.push('sponsored/ugc on internal link');
-    }
-    
-    linkDetails.push({
-      href: href.substring(0, 200),
-      text: text.substring(0, 100),
-      isInternal,
-      isNavigation: isNav,
-      rel,
-      title,
-      issues: linkIssues,
-    });
-  });
-  
-  // Generate anchor text patterns
-  const anchorPatterns = Object.entries(anchorTextCounts)
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 10)
-    .map(([text, count]) => ({ text, count }));
-  
-  // Analyze results
-  const uniqueInternalTargets = internalTargets.size;
-  
-  // Check for orphan risk (very few internal links)
-  const orphanRisk = internalLinks < 3 && contentLinks < 2;
-  
-  // Generate issues
-  if (internalLinks === 0) {
-    issues.push({
-      code: 'LINK_NO_INTERNAL',
-      severity: 'critical',
-      category: 'content',
-      title: 'No internal links found',
-      description: 'This page has no internal links to other pages on your site.',
-      impact: 'Poor link equity distribution, crawlability issues',
-      howToFix: 'Add relevant internal links to other pages on your site.',
-      affectedUrls: [url],
-    });
-    score -= 25;
-  } else if (contentLinks === 0 && internalLinks < 5) {
-    issues.push({
-      code: 'LINK_LOW_INTERNAL',
-      severity: 'warning',
-      category: 'content',
-      title: 'Very few internal links in content',
-      description: `Only ${internalLinks} internal links found, all in navigation.`,
-      impact: 'Limited topic relevance signals',
-      howToFix: 'Add contextual internal links within your content.',
-      affectedUrls: [url],
-    });
-    score -= 15;
-  }
-  
-  if (linksWithGenericText > 3) {
-    const percentage = Math.round((linksWithGenericText / totalLinks) * 100);
-    issues.push({
-      code: 'LINK_GENERIC_ANCHOR',
-      severity: 'warning',
-      category: 'content',
-      title: `${linksWithGenericText} links with generic anchor text`,
-      description: `${percentage}% of links use non-descriptive text like "click here" or "read more".`,
-      impact: 'Missed keyword relevance signals',
-      howToFix: 'Replace generic anchors with descriptive, keyword-rich text.',
-      affectedUrls: [url],
-    });
-    score -= Math.min(linksWithGenericText * 2, 15);
-  }
-  
-  if (emptyAnchorLinks > 0) {
-    issues.push({
-      code: 'LINK_EMPTY_ANCHOR',
-      severity: 'warning',
-      category: 'content',
-      title: `${emptyAnchorLinks} links with empty anchor text`,
-      description: 'Links without text or alt text are inaccessible and provide no SEO value.',
-      impact: 'Accessibility issues, wasted link equity',
-      howToFix: 'Add descriptive text or ensure image links have alt text.',
-      affectedUrls: [url],
-    });
-    score -= Math.min(emptyAnchorLinks * 3, 15);
-  }
-  
-  if (orphanRisk) {
-    issues.push({
-      code: 'LINK_ORPHAN_RISK',
-      severity: 'info',
-      category: 'content',
-      title: 'Page may be an orphan',
-      description: 'This page has very few internal links, which may indicate it\'s poorly connected in your site structure.',
-      impact: 'Difficult for users and crawlers to find',
-      howToFix: 'Link to this page from related content and relevant hub pages.',
-      affectedUrls: [url],
-    });
-    score -= 10;
-  }
-  
-  // Check internal link nofollow
-  const nofollowInternalLinks = linkDetails.filter(l => l.isInternal && l.rel?.includes('nofollow'));
-  if (nofollowInternalLinks.length > 0) {
-    issues.push({
-      code: 'LINK_NOFOLLOW_INTERNAL',
-      severity: 'warning',
-      category: 'technical',
-      title: `${nofollowInternalLinks.length} internal links with nofollow`,
-      description: 'Internal links should not have nofollow - it wastes PageRank.',
-      impact: 'Reduced internal link equity flow',
-      howToFix: 'Remove nofollow from internal links.',
-      affectedUrls: [url],
-    });
-    score -= nofollowInternalLinks.length * 3;
-  }
-  
-  // Check for excessive external links
-  if (externalLinks > internalLinks && externalLinks > 10) {
-    issues.push({
-      code: 'LINK_EXTERNAL_HEAVY',
-      severity: 'info',
-      category: 'content',
-      title: 'More external links than internal',
-      description: `${externalLinks} external vs ${internalLinks} internal links.`,
-      impact: 'May leak PageRank to external sites',
-      howToFix: 'Consider adding more internal links or using nofollow/sponsored for some external links.',
-      affectedUrls: [url],
-    });
-  }
-  
-  // Recommendations
-  if (contentLinks < 3 && internalLinks > 0) {
-    recommendations.push('Add 2-3 contextual internal links within your content');
-  }
-  
-  if (linksWithKeywords / Math.max(totalLinks, 1) > 0.7) {
-    recommendations.push('✓ Good use of descriptive anchor text');
-  }
-  
-  if (uniqueInternalTargets > 5) {
-    recommendations.push('✓ Good diversity of internal link targets');
-  }
-  
-  // Suggest hub pages
-  if (internalLinks > 10) {
-    recommendations.push('Consider creating a hub/pillar page to consolidate topic authority');
-  }
-  
-  return {
-    score: Math.max(0, Math.min(100, score)),
-    totalLinks,
-    internalLinks,
-    externalLinks,
-    navigationLinks,
-    contentLinks,
-    uniqueInternalTargets,
-    linksWithKeywords,
-    linksWithGenericText,
-    orphanRisk,
-    linkDetails,
-    anchorTextAnalysis: {
-      total: totalLinks,
-      descriptive: linksWithKeywords,
-      generic: linksWithGenericText,
-      empty: emptyAnchorLinks,
-      tooLong: tooLongAnchorLinks,
-      imageLinks,
-      patterns: anchorPatterns,
-    },
-    issues,
-    recommendations,
-  };
-}
-
-/**
- * Suggest internal linking opportunities
- */
-export function suggestInternalLinks(content: string, availablePages: { url: string; title: string; keywords: string[] }[]): {
-  keyword: string;
-  suggestedUrl: string;
-  suggestedTitle: string;
-  relevance: number;
-}[] {
-  const suggestions: { keyword: string; suggestedUrl: string; suggestedTitle: string; relevance: number }[] = [];
-  const contentLower = content.toLowerCase();
-  
-  for (const page of availablePages) {
-    for (const keyword of page.keywords) {
-      if (contentLower.includes(keyword.toLowerCase())) {
-        // Check if not already linked
-        const alreadyLinked = content.includes(`href="${page.url}"`) || 
-                              content.includes(`href='${page.url}'`);
-        
-        if (!alreadyLinked) {
-          // Simple relevance: keyword length + position
-          const position = contentLower.indexOf(keyword.toLowerCase());
-          const relevance = (keyword.length * 2) + (1000 - Math.min(position, 1000)) / 100;
-          
-          suggestions.push({
-            keyword,
-            suggestedUrl: page.url,
-            suggestedTitle: page.title,
-            relevance,
-          });
-        }
-      }
-    }
-  }
-  
-  // Sort by relevance and dedupe
-  return suggestions
-    .sort((a, b) => b.relevance - a.relevance)
-    .filter((s, i, arr) => arr.findIndex(x => x.suggestedUrl === s.suggestedUrl) === i)
-    .slice(0, 10);
-}

package/src/analyzers/mobile-seo-analyzer.test.ts

@@ -1,140 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { analyzeMobileSEO } from './mobile-seo-analyzer.js';
-
-describe('Mobile SEO Analyzer', () => {
-  describe('analyzeMobileSEO', () => {
-    it('detects proper viewport', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-</head>
-<body><h1>Test</h1></body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.viewport.hasViewport).toBe(true);
-      expect(result.viewport.isResponsive).toBe(true);
-    });
-
-    it('detects missing viewport', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head><title>Test</title></head>
-<body><h1>Test</h1></body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.viewport.hasViewport).toBe(false);
-      expect(result.issues.some(i => i.code === 'MOBILE_NO_VIEWPORT')).toBe(true);
-    });
-
-    it('detects fixed viewport width', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta name="viewport" content="width=1024">
-</head>
-<body><h1>Test</h1></body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.viewport.isResponsive).toBe(false);
-    });
-
-    it('warns about disabled zooming', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta name="viewport" content="width=device-width, user-scalable=no">
-</head>
-<body><h1>Test</h1></body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.issues.some(i => i.code === 'MOBILE_ZOOM_DISABLED')).toBe(true);
-    });
-
-    it('detects apple touch icon', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <link rel="apple-touch-icon" href="/apple-touch-icon.png">
-</head>
-<body><h1>Test</h1></body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.mobileSpecific.hasAppleTouchIcon).toBe(true);
-    });
-
-    it('detects theme color', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <meta name="theme-color" content="#ffffff">
-</head>
-<body><h1>Test</h1></body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.mobileSpecific.hasThemeColor).toBe(true);
-    });
-
-    it('detects web app manifest', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <link rel="manifest" href="/manifest.json">
-</head>
-<body><h1>Test</h1></body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.mobileSpecific.hasManifest).toBe(true);
-    });
-
-    it('detects responsive images', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-</head>
-<body>
-  <img srcset="/image-400.jpg 400w, /image-800.jpg 800w" src="/image.jpg" alt="Test">
-</body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.mobileSpecific.hasMobileOptimizedImages).toBe(true);
-    });
-
-    it('calculates overall score', () => {
-      const html = `
-<!DOCTYPE html>
-<html>
-<head>
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <meta name="theme-color" content="#000000">
-  <link rel="manifest" href="/manifest.json">
-  <link rel="apple-touch-icon" href="/icon.png">
-</head>
-<body><h1>Test</h1></body>
-</html>
-`;
-      const result = analyzeMobileSEO(html, 'https://example.com');
-      expect(result.score).toBeGreaterThan(80);
-    });
-  });
-});