@rankcli/agent-runtime 0.0.1

package/src/audit/checks/anchor-text.ts

@@ -0,0 +1,179 @@
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+import { ISSUE_DEFINITIONS } from '../types.js';
+
+export interface AnchorTextData {
+  totalLinks: number;
+  internalLinks: number;
+  externalLinks: number;
+  emptyAnchors: number;
+  genericAnchors: number;
+  anchorDistribution: Record<string, number>;
+  topAnchors: { text: string; count: number }[];
+}
+
+// Generic anchor text patterns
+const GENERIC_ANCHORS = new Set([
+  'click here',
+  'click',
+  'here',
+  'read more',
+  'more',
+  'learn more',
+  'see more',
+  'view more',
+  'continue',
+  'continue reading',
+  'link',
+  'this',
+  'this link',
+  'go',
+  'details',
+  'more details',
+  'more info',
+  'info',
+  'read',
+  'view',
+  'see',
+  'download',
+  'get it',
+  'get',
+]);
+
+export function analyzeAnchorText(
+  html: string,
+  url: string
+): { issues: AuditIssue[]; data: AnchorTextData } {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+
+  const baseUrl = new URL(url);
+  const anchorCounts: Record<string, number> = {};
+  let totalLinks = 0;
+  let internalLinks = 0;
+  let externalLinks = 0;
+  let emptyAnchors = 0;
+  let genericAnchors = 0;
+  const emptyAnchorUrls: string[] = [];
+  const genericAnchorExamples: string[] = [];
+
+  $('a[href]').each((_, el) => {
+    const href = $(el).attr('href') || '';
+    const text = $(el).text().trim().toLowerCase();
+    const ariaLabel = $(el).attr('aria-label')?.trim();
+    const title = $(el).attr('title')?.trim();
+
+    // Skip non-navigation links
+    if (href.startsWith('#') || href.startsWith('javascript:') || href.startsWith('mailto:') || href.startsWith('tel:')) {
+      return;
+    }
+
+    totalLinks++;
+
+    // Determine if internal or external
+    try {
+      const linkUrl = new URL(href, url);
+      if (linkUrl.hostname === baseUrl.hostname) {
+        internalLinks++;
+      } else {
+        externalLinks++;
+      }
+    } catch {
+      internalLinks++; // Relative URLs are internal
+    }
+
+    // Check for empty anchor text
+    const hasAccessibleText = text.length > 0 || ariaLabel || title;
+    if (!hasAccessibleText) {
+      emptyAnchors++;
+      if (emptyAnchorUrls.length < 5) {
+        emptyAnchorUrls.push(href);
+      }
+      return;
+    }
+
+    // Check for generic anchor text
+    if (GENERIC_ANCHORS.has(text)) {
+      genericAnchors++;
+      if (genericAnchorExamples.length < 5) {
+        genericAnchorExamples.push(text);
+      }
+    }
+
+    // Track anchor text distribution
+    if (text.length > 0) {
+      anchorCounts[text] = (anchorCounts[text] || 0) + 1;
+    }
+  });
+
+  // Calculate top anchors
+  const topAnchors = Object.entries(anchorCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([text, count]) => ({ text, count }));
+
+  const data: AnchorTextData = {
+    totalLinks,
+    internalLinks,
+    externalLinks,
+    emptyAnchors,
+    genericAnchors,
+    anchorDistribution: anchorCounts,
+    topAnchors,
+  };
+
+  // ==================== Issue Detection ====================
+
+  // Empty anchors
+  if (emptyAnchors > 0) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.ANCHOR_TEXT_EMPTY,
+      affectedUrls: [url],
+      details: {
+        count: emptyAnchors,
+        examples: emptyAnchorUrls,
+      },
+    });
+  }
+
+  // Generic anchors (only flag if significant portion)
+  const genericRatio = totalLinks > 0 ? genericAnchors / totalLinks : 0;
+  if (genericAnchors >= 3 && genericRatio > 0.2) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.ANCHOR_TEXT_GENERIC,
+      affectedUrls: [url],
+      details: {
+        count: genericAnchors,
+        ratio: `${(genericRatio * 100).toFixed(1)}%`,
+        examples: genericAnchorExamples,
+      },
+    });
+  }
+
+  // Over-optimized anchor text detection
+  // Check if any single anchor text is used too frequently
+  const overOptimizedAnchors: string[] = [];
+  for (const [text, count] of Object.entries(anchorCounts)) {
+    // Exclude very short or very long texts
+    if (text.length < 3 || text.length > 50) continue;
+    // Exclude common navigation items
+    if (['home', 'about', 'contact', 'blog', 'services', 'products'].includes(text)) continue;
+
+    // Flag if same anchor used more than 5 times and represents >15% of links
+    if (count > 5 && count / internalLinks > 0.15) {
+      overOptimizedAnchors.push(`"${text}" (${count} times)`);
+    }
+  }
+
+  if (overOptimizedAnchors.length > 0) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.ANCHOR_TEXT_OVER_OPTIMIZED,
+      affectedUrls: [url],
+      details: {
+        overOptimized: overOptimizedAnchors,
+      },
+    });
+  }
+
+  return { issues, data };
+}

package/src/audit/checks/answer-conciseness.ts

@@ -0,0 +1,322 @@
+/**
+ * Answer Conciseness Checks
+ *
+ * AI systems prefer succinct, quotable answers. Content that provides
+ * clear, direct answers to questions is more likely to be cited.
+ * This check analyzes answer quality and quotability.
+ */
+
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+
+export interface AnswerConcisenessData {
+  headings: {
+    total: number;
+    questions: number;
+    withDirectAnswers: number;
+  };
+  answers: {
+    averageFirstSentenceLength: number;
+    shortAnswersCount: number;
+    longAnswersCount: number;
+    quotableAnswers: string[];
+  };
+  definitions: {
+    count: number;
+    examples: string[];
+  };
+  keyTakeaways: {
+    hasSummary: boolean;
+    hasTLDR: boolean;
+    hasKeyPoints: boolean;
+  };
+  concisenessScore: number;
+}
+
+// Ideal answer lengths for AI
+const IDEAL_ANSWER_LENGTH = { min: 40, max: 150 }; // Characters
+const MAX_FIRST_SENTENCE = 200; // Characters
+
+export function analyzeAnswerConciseness(
+  html: string,
+  url: string
+): { issues: AuditIssue[]; data: AnswerConcisenessData } {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+
+  // Remove non-content elements
+  $('nav, footer, aside, script, style, noscript, header').remove();
+
+  const headings = $('h1, h2, h3, h4, h5, h6');
+  let totalHeadings = 0;
+  let questionHeadings = 0;
+  let headingsWithDirectAnswers = 0;
+
+  const firstSentenceLengths: number[] = [];
+  let shortAnswersCount = 0;
+  let longAnswersCount = 0;
+  const quotableAnswers: string[] = [];
+
+  // Question patterns
+  const questionPatterns = [
+    /\?$/,
+    /^(what|how|why|when|where|who|which|can|does|is|are|should|will|would|could)\s/i,
+  ];
+
+  headings.each((_, heading) => {
+    const $heading = $(heading);
+    const headingText = $heading.text().trim();
+    totalHeadings++;
+
+    // Check if heading is a question
+    const isQuestion = questionPatterns.some(p => p.test(headingText));
+
+    if (isQuestion) {
+      questionHeadings++;
+
+      // Get the content after this heading until the next heading
+      let $next = $heading.next();
+      let answerText = '';
+
+      while ($next.length && !$next.is('h1, h2, h3, h4, h5, h6')) {
+        if ($next.is('p')) {
+          answerText += $next.text().trim() + ' ';
+        }
+        $next = $next.next();
+      }
+
+      if (answerText) {
+        // Get first sentence
+        const firstSentenceMatch = answerText.match(/^[^.!?]+[.!?]/);
+        const firstSentence = firstSentenceMatch ? firstSentenceMatch[0].trim() : '';
+
+        if (firstSentence) {
+          firstSentenceLengths.push(firstSentence.length);
+
+          // Check if it's a direct answer (short, complete, starts definitively)
+          const isDirectAnswer =
+            firstSentence.length <= MAX_FIRST_SENTENCE &&
+            !firstSentence.toLowerCase().startsWith('well,') &&
+            !firstSentence.toLowerCase().startsWith('so,') &&
+            !firstSentence.toLowerCase().startsWith('basically,') &&
+            (
+              /^(yes|no|the|a|an|it|they|this|there|you|we)/i.test(firstSentence) ||
+              /^[A-Z][a-z]+\s+(is|are|was|were|can|should|will)/i.test(firstSentence)
+            );
+
+          if (isDirectAnswer) {
+            headingsWithDirectAnswers++;
+
+            // Check if quotable (ideal length)
+            if (firstSentence.length >= IDEAL_ANSWER_LENGTH.min &&
+                firstSentence.length <= IDEAL_ANSWER_LENGTH.max) {
+              shortAnswersCount++;
+              quotableAnswers.push(firstSentence);
+            } else if (firstSentence.length > IDEAL_ANSWER_LENGTH.max) {
+              longAnswersCount++;
+            }
+          }
+        }
+      }
+    }
+  });
+
+  // Detect definitions
+  const definitions: string[] = [];
+  $('p').each((_, p) => {
+    const text = $(p).text().trim();
+
+    // Definition patterns: "X is a...", "X refers to...", "X means..."
+    const defMatch = text.match(/^([A-Z][^.]{0,50})\s+(is|are|refers to|means|describes|represents)\s+([^.]+\.)/);
+    if (defMatch) {
+      definitions.push(defMatch[0]);
+    }
+  });
+
+  // Check for summary elements
+  const bodyText = $('body').text().toLowerCase();
+  const headingText = headings.map((_, h) => $(h).text().toLowerCase()).get().join(' ');
+
+  const hasSummary =
+    headingText.includes('summary') ||
+    headingText.includes('conclusion') ||
+    headingText.includes('key takeaways') ||
+    $('[class*="summary"], [id*="summary"]').length > 0;
+
+  const hasTLDR =
+    bodyText.includes('tl;dr') ||
+    bodyText.includes('tldr') ||
+    bodyText.includes('in short') ||
+    bodyText.includes('in summary') ||
+    headingText.includes('tl;dr');
+
+  const hasKeyPoints =
+    headingText.includes('key points') ||
+    headingText.includes('main points') ||
+    headingText.includes('highlights') ||
+    $('[class*="key-points"], [class*="highlights"]').length > 0;
+
+  // Calculate average first sentence length
+  const averageFirstSentenceLength = firstSentenceLengths.length > 0
+    ? firstSentenceLengths.reduce((a, b) => a + b, 0) / firstSentenceLengths.length
+    : 0;
+
+  // Calculate conciseness score
+  let concisenessScore = 50;
+
+  // Question/answer quality
+  if (questionHeadings > 0) {
+    const answerRatio = headingsWithDirectAnswers / questionHeadings;
+    concisenessScore += answerRatio * 20;
+  }
+
+  // Quotable answers bonus
+  if (shortAnswersCount >= 3) concisenessScore += 15;
+  else if (shortAnswersCount >= 1) concisenessScore += 10;
+
+  // Long answers penalty
+  if (longAnswersCount > shortAnswersCount) concisenessScore -= 10;
+
+  // Definitions bonus
+  if (definitions.length >= 2) concisenessScore += 10;
+  else if (definitions.length === 1) concisenessScore += 5;
+
+  // Summary elements bonus
+  if (hasSummary) concisenessScore += 5;
+  if (hasTLDR) concisenessScore += 5;
+  if (hasKeyPoints) concisenessScore += 5;
+
+  // Average sentence length
+  if (averageFirstSentenceLength > 0 && averageFirstSentenceLength <= 150) {
+    concisenessScore += 5;
+  } else if (averageFirstSentenceLength > 200) {
+    concisenessScore -= 10;
+  }
+
+  concisenessScore = Math.max(0, Math.min(100, concisenessScore));
+
+  // Generate issues
+
+  // Questions without direct answers
+  if (questionHeadings > 0 && headingsWithDirectAnswers < questionHeadings * 0.5) {
+    issues.push({
+      code: 'AI_INDIRECT_ANSWERS',
+      severity: 'warning',
+      category: 'ai-readiness',
+      title: 'Questions lack direct, quotable answers',
+      description: `${questionHeadings} question headings found but only ${headingsWithDirectAnswers} have direct answers. AI prefers content that answers questions immediately.`,
+      impact: 'AI may skip your content for sources with clearer, more direct answers.',
+      howToFix: 'Start answer paragraphs with a direct 1-2 sentence answer. Avoid filler words like "Well," "So," "Basically." Lead with the answer, then explain.',
+      affectedUrls: [url],
+      details: {
+        questionHeadings,
+        directAnswers: headingsWithDirectAnswers,
+        examples: quotableAnswers.slice(0, 3),
+      },
+    });
+  }
+
+  // Answers too long
+  if (longAnswersCount > 0 && longAnswersCount > shortAnswersCount) {
+    issues.push({
+      code: 'AI_VERBOSE_ANSWERS',
+      severity: 'notice',
+      category: 'ai-readiness',
+      title: 'Answer opening sentences are too long',
+      description: `Found ${longAnswersCount} answers with opening sentences over 150 characters. AI quotes shorter, punchier statements.`,
+      impact: 'Long opening sentences are less likely to be quoted verbatim by AI.',
+      howToFix: 'Keep first sentences under 150 characters. Move details to subsequent sentences. Think "tweet-length" for opening answers.',
+      affectedUrls: [url],
+      details: {
+        averageLength: Math.round(averageFirstSentenceLength),
+        idealLength: `${IDEAL_ANSWER_LENGTH.min}-${IDEAL_ANSWER_LENGTH.max} characters`,
+      },
+    });
+  }
+
+  // No definitions for definitional content
+  const hasDefinitionalQueries =
+    bodyText.includes('what is') ||
+    bodyText.includes('what are') ||
+    bodyText.includes('definition') ||
+    bodyText.includes('meaning of');
+
+  if (hasDefinitionalQueries && definitions.length === 0) {
+    issues.push({
+      code: 'AI_NO_CLEAR_DEFINITIONS',
+      severity: 'notice',
+      category: 'ai-readiness',
+      title: 'Definitional content lacks clear definitions',
+      description: 'Content discusses "what is" topics but lacks Wikipedia-style definitions. AI heavily favors clear "[Term] is a [definition]" patterns.',
+      impact: 'Missing out on definitional search citations and AI answer boxes.',
+      howToFix: 'Add clear definitions: "[Term] is a [category] that [key characteristics]." Place definitions early in content or in dedicated sections.',
+      affectedUrls: [url],
+      details: {
+        suggestion: 'Example: "SEO is the practice of optimizing websites to rank higher in search engine results."',
+      },
+    });
+  }
+
+  // No summary or TLDR
+  const wordCount = $('body').text().split(/\s+/).length;
+  if (wordCount > 1500 && !hasSummary && !hasTLDR && !hasKeyPoints) {
+    issues.push({
+      code: 'AI_NO_SUMMARY',
+      severity: 'notice',
+      category: 'ai-readiness',
+      title: 'Long content lacks summary or key takeaways',
+      description: 'Content is over 1500 words but has no summary, TL;DR, or key points section. AI often pulls from summary sections.',
+      impact: 'Harder for AI to extract key points; may cite competitors with better-structured summaries.',
+      howToFix: 'Add a "Key Takeaways" section at the top or a "Summary" at the bottom. Use bullet points for scannable key points.',
+      affectedUrls: [url],
+    });
+  }
+
+  // Low conciseness score
+  if (concisenessScore < 50) {
+    issues.push({
+      code: 'AI_LOW_CONCISENESS',
+      severity: 'warning',
+      category: 'ai-readiness',
+      title: 'Content lacks concise, quotable answers',
+      description: `Conciseness score: ${concisenessScore}/100. AI prefers content with clear, succinct answers it can quote directly.`,
+      impact: 'Reduced likelihood of AI citing your content in direct answers.',
+      howToFix: 'Restructure content: lead with direct answers, add definitions, include TL;DR sections, keep opening sentences short.',
+      affectedUrls: [url],
+      details: {
+        concisenessScore,
+        quotableAnswers: quotableAnswers.length,
+        definitions: definitions.length,
+        hasSummary,
+        hasTLDR,
+      },
+    });
+  }
+
+  return {
+    issues,
+    data: {
+      headings: {
+        total: totalHeadings,
+        questions: questionHeadings,
+        withDirectAnswers: headingsWithDirectAnswers,
+      },
+      answers: {
+        averageFirstSentenceLength: Math.round(averageFirstSentenceLength),
+        shortAnswersCount,
+        longAnswersCount,
+        quotableAnswers: quotableAnswers.slice(0, 5),
+      },
+      definitions: {
+        count: definitions.length,
+        examples: definitions.slice(0, 3),
+      },
+      keyTakeaways: {
+        hasSummary,
+        hasTLDR,
+        hasKeyPoints,
+      },
+      concisenessScore,
+    },
+  };
+}