@rankcli/agent-runtime 0.0.15 → 0.0.17

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

@@ -1,322 +0,0 @@
-/**
- * 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,
-    },
-  };
-}

package/src/audit/checks/asset-minification.ts

@@ -1,270 +0,0 @@
-/**
- * Asset Minification Check
- *
- * Checks if CSS and JavaScript files are properly minified.
- * Unminified files contain unnecessary whitespace, comments, and long variable names
- * that increase file size and slow down page load times.
- *
- * Detection methods:
- * - Whitespace ratio (minified files have very low whitespace)
- * - Average line length (minified files have very long lines)
- * - Comment presence (minified files have no comments)
- */
-
-import { httpGet } from '../../utils/http.js';
-import * as cheerio from 'cheerio';
-import type { AuditIssue } from '../types.js';
-
-export interface MinificationData {
-  cssFiles: AssetMinificationInfo[];
-  jsFiles: AssetMinificationInfo[];
-  totalCssFiles: number;
-  totalJsFiles: number;
-  unminifiedCss: number;
-  unminifiedJs: number;
-  potentialSavings: {
-    css: number; // estimated bytes
-    js: number;
-  };
-}
-
-interface AssetMinificationInfo {
-  url: string;
-  size: number;
-  isMinified: boolean;
-  indicators: {
-    avgLineLength: number;
-    whitespaceRatio: number;
-    hasComments: boolean;
-  };
-}
-
-/**
- * Detect if content is minified
- */
-function isMinified(content: string, type: 'css' | 'js'): { isMinified: boolean; indicators: AssetMinificationInfo['indicators'] } {
-  const lines = content.split('\n');
-  const totalLines = lines.length;
-  const avgLineLength = totalLines > 0 ? content.length / totalLines : 0;
-
-  // Count whitespace characters (spaces, tabs, newlines)
-  const whitespaceCount = (content.match(/\s/g) || []).length;
-  const whitespaceRatio = content.length > 0 ? whitespaceCount / content.length : 0;
-
-  // Check for comments
-  let hasComments = false;
-  if (type === 'css') {
-    // CSS comments: /* ... */
-    hasComments = /\/\*[\s\S]*?\*\//.test(content);
-  } else {
-    // JS comments: // ... or /* ... */
-    hasComments = /\/\/[^\n]*|\/\*[\s\S]*?\*\//.test(content);
-  }
-
-  // Minification indicators:
-  // - Average line length > 500 chars (minified = long lines)
-  // - Whitespace ratio < 10% (minified = little whitespace)
-  // - No comments
-  const isMinifiedByLineLength = avgLineLength > 500;
-  const isMinifiedByWhitespace = whitespaceRatio < 0.1;
-  const isMinifiedByComments = !hasComments;
-
-  // Consider minified if at least 2 of 3 indicators pass
-  // OR if single-line file with reasonable length (common for small minified files)
-  const score = (isMinifiedByLineLength ? 1 : 0) + (isMinifiedByWhitespace ? 1 : 0) + (isMinifiedByComments ? 1 : 0);
-  const isSingleLineMinified = totalLines <= 2 && avgLineLength > 100;
-
-  return {
-    isMinified: score >= 2 || isSingleLineMinified,
-    indicators: {
-      avgLineLength: Math.round(avgLineLength),
-      whitespaceRatio: Math.round(whitespaceRatio * 100) / 100,
-      hasComments,
-    },
-  };
-}
-
-/**
- * Extract asset URLs from HTML
- */
-function extractAssetUrls(html: string, baseUrl: string): { css: string[]; js: string[] } {
-  const $ = cheerio.load(html);
-  const base = new URL(baseUrl);
-  const css: string[] = [];
-  const js: string[] = [];
-
-  // Extract CSS files
-  $('link[rel="stylesheet"][href]').each((_, el) => {
-    const href = $(el).attr('href');
-    if (href && !href.startsWith('data:')) {
-      try {
-        const fullUrl = new URL(href, base).href;
-        // Only check first-party CSS
-        if (new URL(fullUrl).hostname === base.hostname) {
-          css.push(fullUrl);
-        }
-      } catch {
-        // Invalid URL
-      }
-    }
-  });
-
-  // Extract JS files
-  $('script[src]').each((_, el) => {
-    const src = $(el).attr('src');
-    if (src && !src.startsWith('data:')) {
-      try {
-        const fullUrl = new URL(src, base).href;
-        // Only check first-party JS
-        if (new URL(fullUrl).hostname === base.hostname) {
-          js.push(fullUrl);
-        }
-      } catch {
-        // Invalid URL
-      }
-    }
-  });
-
-  return { css, js };
-}
-
-/**
- * Analyze asset minification
- */
-export async function analyzeAssetMinification(
-  html: string,
-  url: string
-): Promise<{ issues: AuditIssue[]; data: MinificationData }> {
-  const issues: AuditIssue[] = [];
-  const assetUrls = extractAssetUrls(html, url);
-
-  const cssFiles: AssetMinificationInfo[] = [];
-  const jsFiles: AssetMinificationInfo[] = [];
-
-  // Check CSS files (limit to 3, parallel with short timeout)
-  const cssToCheck = assetUrls.css.slice(0, 3);
-  const cssPromises = cssToCheck.map(async (cssUrl) => {
-    try {
-      const response = await httpGet<string>(cssUrl, {
-        timeout: 3000, // Reduced timeout
-        validateStatus: () => true,
-      });
-
-      if (response.status === 200 && typeof response.data === 'string') {
-        const content = response.data;
-        const { isMinified: minified, indicators } = isMinified(content, 'css');
-
-        cssFiles.push({
-          url: cssUrl,
-          size: content.length,
-          isMinified: minified,
-          indicators,
-        });
-      }
-    } catch {
-      // Skip failed requests
-    }
-  });
-
-  // Check JS files (limit to 3, parallel with short timeout)
-  const jsToCheck = assetUrls.js.slice(0, 3);
-  const jsPromises = jsToCheck.map(async (jsUrl) => {
-    try {
-      const response = await httpGet<string>(jsUrl, {
-        timeout: 3000, // Reduced timeout
-        validateStatus: () => true,
-      });
-
-      if (response.status === 200 && typeof response.data === 'string') {
-        const content = response.data;
-        const { isMinified: minified, indicators } = isMinified(content, 'js');
-
-        jsFiles.push({
-          url: jsUrl,
-          size: content.length,
-          isMinified: minified,
-          indicators,
-        });
-      }
-    } catch {
-      // Skip failed requests
-    }
-  });
-
-  // Run all checks in parallel with overall timeout
-  await Promise.race([
-    Promise.all([...cssPromises, ...jsPromises]),
-    new Promise<void>((resolve) => setTimeout(resolve, 8000)), // 8s overall timeout
-  ]);
-
-  // Count unminified files
-  const unminifiedCss = cssFiles.filter((f) => !f.isMinified);
-  const unminifiedJs = jsFiles.filter((f) => !f.isMinified);
-
-  // Estimate potential savings (minification typically saves 30-50%)
-  const cssSavings = unminifiedCss.reduce((sum, f) => sum + Math.round(f.size * 0.4), 0);
-  const jsSavings = unminifiedJs.reduce((sum, f) => sum + Math.round(f.size * 0.4), 0);
-
-  // Generate issues
-  if (unminifiedCss.length > 0) {
-    issues.push({
-      code: 'CSS_NOT_MINIFIED',
-      severity: 'warning',
-      category: 'performance',
-      title: 'CSS files not minified',
-      description: `${unminifiedCss.length} CSS file(s) appear to not be minified. Minification removes whitespace and comments to reduce file size.`,
-      impact: `Unminified CSS increases page load time. Potential savings: ~${Math.round(cssSavings / 1024)}KB.`,
-      howToFix:
-        'Use a CSS minifier like cssnano, clean-css, or build tools (Vite, Webpack) to minify CSS files. Most bundlers do this automatically in production builds.',
-      affectedUrls: unminifiedCss.map((f) => f.url),
-      details: {
-        files: unminifiedCss.map((f) => ({
-          url: f.url,
-          size: `${Math.round(f.size / 1024)}KB`,
-          avgLineLength: f.indicators.avgLineLength,
-          whitespaceRatio: `${Math.round(f.indicators.whitespaceRatio * 100)}%`,
-          hasComments: f.indicators.hasComments,
-        })),
-      },
-    });
-  }
-
-  if (unminifiedJs.length > 0) {
-    issues.push({
-      code: 'JS_NOT_MINIFIED',
-      severity: 'warning',
-      category: 'performance',
-      title: 'JavaScript files not minified',
-      description: `${unminifiedJs.length} JavaScript file(s) appear to not be minified. Minification removes whitespace, comments, and shortens variable names.`,
-      impact: `Unminified JavaScript increases page load time and parsing time. Potential savings: ~${Math.round(jsSavings / 1024)}KB.`,
-      howToFix:
-        'Use a JS minifier like Terser, UglifyJS, or build tools (Vite, Webpack, esbuild) to minify JavaScript. Most bundlers do this automatically in production builds.',
-      affectedUrls: unminifiedJs.map((f) => f.url),
-      details: {
-        files: unminifiedJs.map((f) => ({
-          url: f.url,
-          size: `${Math.round(f.size / 1024)}KB`,
-          avgLineLength: f.indicators.avgLineLength,
-          whitespaceRatio: `${Math.round(f.indicators.whitespaceRatio * 100)}%`,
-          hasComments: f.indicators.hasComments,
-        })),
-      },
-    });
-  }
-
-  return {
-    issues,
-    data: {
-      cssFiles,
-      jsFiles,
-      totalCssFiles: assetUrls.css.length,
-      totalJsFiles: assetUrls.js.length,
-      unminifiedCss: unminifiedCss.length,
-      unminifiedJs: unminifiedJs.length,
-      potentialSavings: {
-        css: cssSavings,
-        js: jsSavings,
-      },
-    },
-  };
-}