@rankcli/agent-runtime 0.0.1

package/src/audit/checks/keyword-placement.ts

@@ -0,0 +1,471 @@
+// Keyword Placement Analysis - Critical On-Page SEO Signals
+// Reference: "4 Steps to Rank #1 in Google (2026 SEO Plan)" by Nathan Gotch
+// "Google's leaked documents have a feature called title match score"
+// "Include the primary keyword phrase in the first paragraph"
+
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+
+export interface KeywordPlacementData {
+  detectedKeywords: string[];
+  urlAnalysis: {
+    containsKeyword: boolean;
+    keywordInUrl: string | null;
+    urlSlug: string;
+    isCleanUrl: boolean;
+    hasDynamicParams: boolean;
+  };
+  titleAnalysis: {
+    hasExactMatch: boolean;
+    hasPartialMatch: boolean;
+    titleMatchScore: number; // 0-100 estimated
+    position: 'start' | 'middle' | 'end' | 'none';
+  };
+  h1Analysis: {
+    hasExactMatch: boolean;
+    hasPartialMatch: boolean;
+    h1Text: string | null;
+  };
+  firstParagraphAnalysis: {
+    hasKeyword: boolean;
+    keywordPosition: number | null; // word position
+    firstParagraphPreview: string;
+    isWithinFirst100Words: boolean;
+  };
+  metaDescriptionAnalysis: {
+    hasKeyword: boolean;
+    position: 'start' | 'middle' | 'end' | 'none';
+  };
+  overallPlacementScore: number; // 0-100
+}
+
+/**
+ * Extract likely target keywords from the page
+ * Uses title, H1, and URL to infer the target keyword
+ */
+export function inferTargetKeywords(html: string, url: string): string[] {
+  const $ = cheerio.load(html);
+  const keywords: string[] = [];
+
+  // Extract from title (most reliable signal)
+  const title = $('title').text().trim();
+  if (title) {
+    // Remove brand name patterns (usually after | or -)
+    const cleanTitle = title.split(/[|\-–—]/)[0]?.trim() || title;
+    if (cleanTitle.length > 3 && cleanTitle.length < 100) {
+      keywords.push(cleanTitle.toLowerCase());
+    }
+  }
+
+  // Extract from H1
+  const h1 = $('h1').first().text().trim();
+  if (h1 && h1.length > 3 && h1.length < 100) {
+    keywords.push(h1.toLowerCase());
+  }
+
+  // Extract from URL slug
+  try {
+    const urlPath = new URL(url).pathname;
+    const slug = urlPath.split('/').filter(p => p.length > 0).pop();
+    if (slug) {
+      const cleanSlug = slug.replace(/[-_]/g, ' ').replace(/\.(html?|php|aspx?)$/i, '');
+      if (cleanSlug.length > 3) {
+        keywords.push(cleanSlug.toLowerCase());
+      }
+    }
+  } catch {
+    // Invalid URL
+  }
+
+  // Find common words across all sources to identify the core keyword
+  const wordCounts = new Map<string, number>();
+  for (const kw of keywords) {
+    const words = kw.split(/\s+/).filter(w => w.length > 2);
+    for (const word of words) {
+      wordCounts.set(word, (wordCounts.get(word) || 0) + 1);
+    }
+  }
+
+  // Sort by frequency and return top keywords
+  return [...new Set(keywords)].slice(0, 3);
+}
+
+/**
+ * Analyze URL for keyword presence
+ */
+export function analyzeUrlKeyword(url: string, keywords: string[]): KeywordPlacementData['urlAnalysis'] {
+  try {
+    const parsedUrl = new URL(url);
+    const urlSlug = parsedUrl.pathname.toLowerCase();
+    const slugWords = urlSlug.replace(/[-_/]/g, ' ').trim();
+
+    let containsKeyword = false;
+    let keywordInUrl: string | null = null;
+
+    for (const keyword of keywords) {
+      const kwWords = keyword.toLowerCase().split(/\s+/);
+      // Check if all significant words of the keyword are in the URL
+      const significantWords = kwWords.filter(w => w.length > 2);
+      const matchCount = significantWords.filter(w => slugWords.includes(w)).length;
+
+      if (matchCount >= Math.ceil(significantWords.length * 0.7)) {
+        containsKeyword = true;
+        keywordInUrl = keyword;
+        break;
+      }
+    }
+
+    // Check for clean URL structure
+    const isCleanUrl = !urlSlug.includes('?') &&
+                       !urlSlug.includes('=') &&
+                       !/\d{5,}/.test(urlSlug) && // No long ID numbers
+                       urlSlug.length < 100;
+
+    const hasDynamicParams = parsedUrl.search.length > 0;
+
+    return {
+      containsKeyword,
+      keywordInUrl,
+      urlSlug,
+      isCleanUrl,
+      hasDynamicParams,
+    };
+  } catch {
+    return {
+      containsKeyword: false,
+      keywordInUrl: null,
+      urlSlug: '',
+      isCleanUrl: false,
+      hasDynamicParams: false,
+    };
+  }
+}
+
+/**
+ * Analyze title for keyword match (Title Match Score concept)
+ */
+export function analyzeTitleKeyword(html: string, keywords: string[]): KeywordPlacementData['titleAnalysis'] {
+  const $ = cheerio.load(html);
+  const title = $('title').text().trim().toLowerCase();
+
+  if (!title) {
+    return {
+      hasExactMatch: false,
+      hasPartialMatch: false,
+      titleMatchScore: 0,
+      position: 'none',
+    };
+  }
+
+  let hasExactMatch = false;
+  let hasPartialMatch = false;
+  let position: 'start' | 'middle' | 'end' | 'none' = 'none';
+
+  for (const keyword of keywords) {
+    const kwLower = keyword.toLowerCase();
+
+    // Exact match check
+    if (title.includes(kwLower)) {
+      hasExactMatch = true;
+
+      // Determine position
+      const index = title.indexOf(kwLower);
+      if (index === 0 || index < 5) {
+        position = 'start';
+      } else if (index > title.length - kwLower.length - 10) {
+        position = 'end';
+      } else {
+        position = 'middle';
+      }
+      break;
+    }
+
+    // Partial match (most words present)
+    const kwWords = kwLower.split(/\s+/).filter(w => w.length > 2);
+    const matchCount = kwWords.filter(w => title.includes(w)).length;
+    if (matchCount >= Math.ceil(kwWords.length * 0.6)) {
+      hasPartialMatch = true;
+      position = 'middle';
+    }
+  }
+
+  // Calculate title match score
+  let titleMatchScore = 0;
+  if (hasExactMatch) {
+    titleMatchScore = position === 'start' ? 100 : position === 'middle' ? 80 : 60;
+  } else if (hasPartialMatch) {
+    titleMatchScore = 40;
+  }
+
+  return {
+    hasExactMatch,
+    hasPartialMatch,
+    titleMatchScore,
+    position,
+  };
+}
+
+/**
+ * Analyze H1 for keyword match
+ */
+export function analyzeH1Keyword(html: string, keywords: string[]): KeywordPlacementData['h1Analysis'] {
+  const $ = cheerio.load(html);
+  const h1 = $('h1').first().text().trim();
+  const h1Lower = h1.toLowerCase();
+
+  let hasExactMatch = false;
+  let hasPartialMatch = false;
+
+  for (const keyword of keywords) {
+    const kwLower = keyword.toLowerCase();
+
+    if (h1Lower.includes(kwLower)) {
+      hasExactMatch = true;
+      break;
+    }
+
+    const kwWords = kwLower.split(/\s+/).filter(w => w.length > 2);
+    const matchCount = kwWords.filter(w => h1Lower.includes(w)).length;
+    if (matchCount >= Math.ceil(kwWords.length * 0.6)) {
+      hasPartialMatch = true;
+    }
+  }
+
+  return {
+    hasExactMatch,
+    hasPartialMatch,
+    h1Text: h1 || null,
+  };
+}
+
+/**
+ * Analyze first paragraph for keyword placement
+ */
+export function analyzeFirstParagraph(html: string, keywords: string[]): KeywordPlacementData['firstParagraphAnalysis'] {
+  const $ = cheerio.load(html);
+
+  // Find the first real paragraph (not in header/nav)
+  const paragraphs = $('main p, article p, .content p, #content p, body > div p').toArray();
+  let firstParagraph = '';
+
+  for (const p of paragraphs) {
+    const text = $(p).text().trim();
+    if (text.length > 50) { // Skip very short paragraphs
+      firstParagraph = text;
+      break;
+    }
+  }
+
+  // Fallback to first p tag
+  if (!firstParagraph) {
+    firstParagraph = $('p').first().text().trim();
+  }
+
+  const firstParagraphLower = firstParagraph.toLowerCase();
+  const words = firstParagraphLower.split(/\s+/);
+
+  let hasKeyword = false;
+  let keywordPosition: number | null = null;
+
+  for (const keyword of keywords) {
+    const kwLower = keyword.toLowerCase();
+    const kwWords = kwLower.split(/\s+/);
+
+    // Find position of first keyword word
+    for (let i = 0; i < words.length; i++) {
+      if (kwWords.some(kw => words[i].includes(kw))) {
+        hasKeyword = true;
+        keywordPosition = i;
+        break;
+      }
+    }
+
+    if (hasKeyword) break;
+  }
+
+  return {
+    hasKeyword,
+    keywordPosition,
+    firstParagraphPreview: firstParagraph.substring(0, 200) + (firstParagraph.length > 200 ? '...' : ''),
+    isWithinFirst100Words: hasKeyword && keywordPosition !== null && keywordPosition < 100,
+  };
+}
+
+/**
+ * Analyze meta description for keyword
+ */
+export function analyzeMetaDescription(html: string, keywords: string[]): KeywordPlacementData['metaDescriptionAnalysis'] {
+  const $ = cheerio.load(html);
+  const metaDesc = $('meta[name="description"]').attr('content')?.trim().toLowerCase() || '';
+
+  if (!metaDesc) {
+    return { hasKeyword: false, position: 'none' };
+  }
+
+  let hasKeyword = false;
+  let position: 'start' | 'middle' | 'end' | 'none' = 'none';
+
+  for (const keyword of keywords) {
+    const kwLower = keyword.toLowerCase();
+    const kwWords = kwLower.split(/\s+/).filter(w => w.length > 2);
+    const matchCount = kwWords.filter(w => metaDesc.includes(w)).length;
+
+    if (matchCount >= Math.ceil(kwWords.length * 0.5)) {
+      hasKeyword = true;
+
+      // Find approximate position
+      const firstMatch = kwWords.find(w => metaDesc.includes(w));
+      if (firstMatch) {
+        const index = metaDesc.indexOf(firstMatch);
+        if (index < 30) {
+          position = 'start';
+        } else if (index > metaDesc.length - 50) {
+          position = 'end';
+        } else {
+          position = 'middle';
+        }
+      }
+      break;
+    }
+  }
+
+  return { hasKeyword, position };
+}
+
+/**
+ * Main function: Analyze keyword placement
+ */
+export function analyzeKeywordPlacement(
+  html: string,
+  url: string
+): { issues: AuditIssue[]; data: KeywordPlacementData } {
+  const issues: AuditIssue[] = [];
+
+  // Infer target keywords
+  const detectedKeywords = inferTargetKeywords(html, url);
+
+  // Run all analyses
+  const urlAnalysis = analyzeUrlKeyword(url, detectedKeywords);
+  const titleAnalysis = analyzeTitleKeyword(html, detectedKeywords);
+  const h1Analysis = analyzeH1Keyword(html, detectedKeywords);
+  const firstParagraphAnalysis = analyzeFirstParagraph(html, detectedKeywords);
+  const metaDescriptionAnalysis = analyzeMetaDescription(html, detectedKeywords);
+
+  // Calculate overall placement score
+  let overallPlacementScore = 0;
+  if (urlAnalysis.containsKeyword) overallPlacementScore += 20;
+  if (titleAnalysis.hasExactMatch) overallPlacementScore += 25;
+  else if (titleAnalysis.hasPartialMatch) overallPlacementScore += 10;
+  if (h1Analysis.hasExactMatch) overallPlacementScore += 20;
+  else if (h1Analysis.hasPartialMatch) overallPlacementScore += 10;
+  if (firstParagraphAnalysis.isWithinFirst100Words) overallPlacementScore += 20;
+  else if (firstParagraphAnalysis.hasKeyword) overallPlacementScore += 10;
+  if (metaDescriptionAnalysis.hasKeyword) overallPlacementScore += 15;
+
+  // Generate issues
+
+  // URL doesn't contain keyword
+  if (!urlAnalysis.containsKeyword && urlAnalysis.urlSlug.length > 1) {
+    issues.push({
+      code: 'URL_MISSING_KEYWORD',
+      severity: 'warning',
+      category: 'on-page',
+      title: 'URL does not contain target keyword',
+      description: `The URL slug "${urlAnalysis.urlSlug}" doesn't include the apparent target keyword.`,
+      impact: 'URLs with keywords help Google understand page relevance. This is a ranking signal.',
+      howToFix: 'Include the primary keyword phrase in the URL (e.g., /keyword-phrase/ instead of /page123/).',
+      affectedUrls: [url],
+      details: {
+        currentSlug: urlAnalysis.urlSlug,
+        inferredKeywords: detectedKeywords,
+      },
+    });
+  }
+
+  // URL has dynamic parameters
+  if (urlAnalysis.hasDynamicParams) {
+    issues.push({
+      code: 'URL_HAS_PARAMS',
+      severity: 'notice',
+      category: 'on-page',
+      title: 'URL contains query parameters',
+      description: 'The URL has query parameters which create a less clean URL structure.',
+      impact: 'Clean, keyword-rich URLs are preferred by search engines and users.',
+      howToFix: 'Use URL rewriting to create clean, parameter-free URLs where possible.',
+      affectedUrls: [url],
+    });
+  }
+
+  // Title doesn't have exact keyword match
+  if (!titleAnalysis.hasExactMatch && detectedKeywords.length > 0) {
+    issues.push({
+      code: 'TITLE_KEYWORD_MISMATCH',
+      severity: 'warning',
+      category: 'on-page',
+      title: 'Title tag missing exact keyword match',
+      description: 'The title tag doesn\'t contain the exact target keyword phrase.',
+      impact: 'Google\'s leaked documents reveal a "title match score" that measures keyword alignment.',
+      howToFix: 'Include the exact target keyword phrase in the title, preferably near the beginning.',
+      affectedUrls: [url],
+      details: {
+        titleMatchScore: titleAnalysis.titleMatchScore,
+        position: titleAnalysis.position,
+      },
+    });
+  }
+
+  // Keyword not in first paragraph
+  if (!firstParagraphAnalysis.hasKeyword) {
+    issues.push({
+      code: 'FIRST_PARA_NO_KEYWORD',
+      severity: 'warning',
+      category: 'on-page',
+      title: 'Primary keyword not in first paragraph',
+      description: 'The target keyword doesn\'t appear in the opening paragraph.',
+      impact: 'Including keywords early in content signals relevance to search engines.',
+      howToFix: 'Add the primary keyword naturally within the first 100 words of your content.',
+      affectedUrls: [url],
+      details: {
+        preview: firstParagraphAnalysis.firstParagraphPreview,
+      },
+    });
+  } else if (!firstParagraphAnalysis.isWithinFirst100Words) {
+    issues.push({
+      code: 'KEYWORD_TOO_FAR',
+      severity: 'notice',
+      category: 'on-page',
+      title: 'Keyword appears late in first paragraph',
+      description: `Keyword found at word position ${firstParagraphAnalysis.keywordPosition}, ideally should be in first 100 words.`,
+      impact: 'Earlier keyword placement may slightly improve relevance signals.',
+      howToFix: 'Move the keyword mention closer to the beginning of your content.',
+      affectedUrls: [url],
+    });
+  }
+
+  // H1 missing keyword
+  if (!h1Analysis.hasExactMatch && !h1Analysis.hasPartialMatch && h1Analysis.h1Text) {
+    issues.push({
+      code: 'H1_MISSING_KEYWORD',
+      severity: 'notice',
+      category: 'on-page',
+      title: 'H1 doesn\'t contain target keyword',
+      description: `The H1 "${h1Analysis.h1Text}" doesn't include the target keyword.`,
+      impact: 'H1 is a strong on-page signal for topic relevance.',
+      howToFix: 'Include the primary keyword in your H1 headline.',
+      affectedUrls: [url],
+    });
+  }
+
+  return {
+    issues,
+    data: {
+      detectedKeywords,
+      urlAnalysis,
+      titleAnalysis,
+      h1Analysis,
+      firstParagraphAnalysis,
+      metaDescriptionAnalysis,
+      overallPlacementScore,
+    },
+  };
+}

package/src/audit/checks/links.ts

@@ -0,0 +1,203 @@
+import * as cheerio from 'cheerio';
+import { httpHead } from '../../utils/http.js';
+import type { AuditIssue } from '../types.js';
+import { ISSUE_DEFINITIONS } from '../types.js';
+
+export interface LinkData {
+  internal: { href: string; text: string; nofollow: boolean }[];
+  external: { href: string; text: string; nofollow: boolean }[];
+  totalLinks: number;
+  brokenInternal: string[];
+  brokenExternal: string[];
+  ratio: {
+    internal: number;
+    external: number;
+    internalToExternalRatio: number | null; // null if no external links
+  };
+}
+
+export async function analyzeLinks(
+  html: string,
+  baseUrl: string,
+  checkBroken: boolean = false
+): Promise<{ issues: AuditIssue[]; data: LinkData }> {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+  const baseHostname = new URL(baseUrl).hostname;
+
+  const internal: LinkData['internal'] = [];
+  const external: LinkData['external'] = [];
+  const brokenInternal: string[] = [];
+  const brokenExternal: string[] = [];
+
+  // Extract all links
+  $('a[href]').each((_, el) => {
+    const href = $(el).attr('href') || '';
+    const text = $(el).text().trim();
+    const rel = $(el).attr('rel') || '';
+    const nofollow = rel.includes('nofollow');
+
+    // Skip javascript:, mailto:, tel:, and anchor links
+    if (href.startsWith('javascript:') || href.startsWith('mailto:') ||
+        href.startsWith('tel:') || href.startsWith('#')) {
+      return;
+    }
+
+    try {
+      const fullUrl = new URL(href, baseUrl).href;
+      const linkHostname = new URL(fullUrl).hostname;
+      const isInternal = linkHostname === baseHostname;
+
+      if (isInternal) {
+        internal.push({ href: fullUrl, text, nofollow });
+        if (nofollow) {
+          issues.push({
+            ...ISSUE_DEFINITIONS.NOFOLLOW_INTERNAL,
+            affectedUrls: [baseUrl],
+            details: { link: fullUrl, anchorText: text },
+          });
+        }
+      } else {
+        external.push({ href: fullUrl, text, nofollow });
+      }
+    } catch {
+      // Invalid URL, skip
+    }
+  });
+
+  const totalLinks = internal.length + external.length;
+
+  // Calculate link ratio
+  const internalCount = internal.length;
+  const externalCount = external.length;
+  const internalToExternalRatio = externalCount > 0 ? internalCount / externalCount : null;
+
+  // Check for too many links
+  if (totalLinks > 100) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.TOO_MANY_LINKS,
+      affectedUrls: [baseUrl],
+      details: { totalLinks, internal: internalCount, external: externalCount },
+    });
+  }
+
+  // Check for no internal links (bad for crawlability and user navigation)
+  if (internalCount === 0 && totalLinks > 0) {
+    issues.push({
+      code: 'LINKS_NO_INTERNAL',
+      severity: 'warning',
+      category: 'links',
+      title: 'No internal links found',
+      description: 'This page has no internal links to other pages on your site.',
+      impact: 'Internal links are crucial for SEO. They help search engines discover pages and distribute link equity throughout your site.',
+      howToFix: 'Add relevant internal links to related content, navigation, or related articles section.',
+      affectedUrls: [baseUrl],
+      details: { totalLinks, external: externalCount },
+    });
+  }
+
+  // Check for no external links (pages should reference external resources)
+  if (externalCount === 0 && totalLinks > 5) {
+    issues.push({
+      code: 'LINKS_NO_EXTERNAL',
+      severity: 'notice',
+      category: 'links',
+      title: 'No external links found',
+      description: 'This page has no links to external websites.',
+      impact: 'Linking to high-quality external sources can improve credibility and help search engines understand your content context.',
+      howToFix: 'Add links to authoritative external sources that support your content. This builds trust and provides value to readers.',
+      affectedUrls: [baseUrl],
+      details: { totalLinks, internal: internalCount },
+    });
+  }
+
+  // Check for poor internal-to-external ratio (too many external vs internal)
+  if (externalCount > internalCount && externalCount > 5 && internalCount < 3) {
+    issues.push({
+      code: 'LINKS_RATIO_POOR',
+      severity: 'warning',
+      category: 'links',
+      title: 'Poor internal-to-external link ratio',
+      description: `Page has ${externalCount} external links but only ${internalCount} internal links.`,
+      impact: 'A healthy page should have more internal links than external links. Too many external links can dilute page authority and may look spammy.',
+      howToFix: 'Add more relevant internal links to balance the ratio. Aim for at least 2-3 internal links for every external link.',
+      affectedUrls: [baseUrl],
+      details: {
+        internal: internalCount,
+        external: externalCount,
+        ratio: internalToExternalRatio ? `1:${(1/internalToExternalRatio).toFixed(1)}` : 'N/A',
+        recommendation: 'Aim for a ratio of at least 2:1 (internal:external)',
+      },
+    });
+  }
+
+  // Check for broken links (limited to avoid too many requests)
+  if (checkBroken) {
+    // Check internal links (up to 10)
+    const internalToCheck = internal.slice(0, 10);
+    for (const link of internalToCheck) {
+      try {
+        const response = await httpHead(link.href, {
+          timeout: 5000,
+          maxRedirects: 5,
+          validateStatus: () => true,
+        });
+        if (response.status >= 400) {
+          brokenInternal.push(link.href);
+        }
+      } catch {
+        brokenInternal.push(link.href);
+      }
+    }
+
+    // Check external links (up to 5)
+    const externalToCheck = external.slice(0, 5);
+    for (const link of externalToCheck) {
+      try {
+        const response = await httpHead(link.href, {
+          timeout: 5000,
+          maxRedirects: 5,
+          validateStatus: () => true,
+        });
+        if (response.status >= 400) {
+          brokenExternal.push(link.href);
+        }
+      } catch {
+        // Don't count timeouts as broken for external links
+      }
+    }
+
+    // Add issues for broken links
+    for (const brokenLink of brokenInternal) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.BROKEN_INTERNAL_LINK,
+        affectedUrls: [baseUrl],
+        details: { brokenLink },
+      });
+    }
+
+    for (const brokenLink of brokenExternal) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.BROKEN_EXTERNAL_LINK,
+        affectedUrls: [baseUrl],
+        details: { brokenLink },
+      });
+    }
+  }
+
+  return {
+    issues,
+    data: {
+      internal,
+      external,
+      totalLinks,
+      brokenInternal,
+      brokenExternal,
+      ratio: {
+        internal: internalCount,
+        external: externalCount,
+        internalToExternalRatio,
+      },
+    }
+  };
+}