@rankcli/agent-runtime 0.0.1

package/src/audit/checks/on-page.ts

@@ -0,0 +1,209 @@
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+import { ISSUE_DEFINITIONS } from '../types.js';
+
+export interface OnPageData {
+  title?: string;
+  titleLength: number;
+  description?: string;
+  descriptionLength: number;
+  canonical?: string;
+  h1s: string[];
+  headings: { level: number; text: string }[];
+  wordCount: number;
+  textToHtmlRatio: number;
+  hasNoindex: boolean;
+  metaRobots?: string;
+}
+
+export function analyzeOnPage(html: string, url: string): { issues: AuditIssue[]; data: OnPageData } {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+
+  // Extract data
+  const title = $('title').text().trim();
+  const description = $('meta[name="description"]').attr('content')?.trim();
+  const canonical = $('link[rel="canonical"]').attr('href');
+  const metaRobots = $('meta[name="robots"]').attr('content');
+
+  // Check noindex
+  const hasNoindex = metaRobots?.toLowerCase().includes('noindex') || false;
+
+  // Extract headings
+  const h1s: string[] = [];
+  $('h1').each((_, el) => {
+    h1s.push($(el).text().trim());
+  });
+
+  const headings: { level: number; text: string }[] = [];
+  $('h1, h2, h3, h4, h5, h6').each((_, el) => {
+    const level = parseInt(el.tagName.charAt(1), 10);
+    headings.push({ level, text: $(el).text().trim() });
+  });
+
+  // Calculate word count (text content only)
+  const bodyText = $('body').text().replace(/\s+/g, ' ').trim();
+  const wordCount = bodyText.split(/\s+/).filter(w => w.length > 0).length;
+
+  // Calculate text-to-HTML ratio
+  const textLength = bodyText.length;
+  const htmlLength = html.length;
+  const textToHtmlRatio = htmlLength > 0 ? (textLength / htmlLength) * 100 : 0;
+
+  const data: OnPageData = {
+    title: title || undefined,
+    titleLength: title?.length || 0,
+    description,
+    descriptionLength: description?.length || 0,
+    canonical,
+    h1s,
+    headings,
+    wordCount,
+    textToHtmlRatio,
+    hasNoindex,
+    metaRobots,
+  };
+
+  // ==================== TITLE CHECKS ====================
+  if (!title) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.TITLE_MISSING,
+      affectedUrls: [url],
+    });
+  } else {
+    if (title.length < 30) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.TITLE_TOO_SHORT,
+        affectedUrls: [url],
+        details: { title, length: title.length },
+      });
+    } else if (title.length > 60) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.TITLE_TOO_LONG,
+        affectedUrls: [url],
+        details: { title, length: title.length },
+      });
+    }
+  }
+
+  // ==================== META DESCRIPTION CHECKS ====================
+  if (!description) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.META_DESC_MISSING,
+      affectedUrls: [url],
+    });
+  } else {
+    if (description.length < 120) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.META_DESC_TOO_SHORT,
+        affectedUrls: [url],
+        details: { description, length: description.length },
+      });
+    } else if (description.length > 160) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.META_DESC_TOO_LONG,
+        affectedUrls: [url],
+        details: { description, length: description.length },
+      });
+    }
+  }
+
+  // ==================== CANONICAL CHECKS ====================
+  if (!canonical) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.CANONICAL_MISSING,
+      affectedUrls: [url],
+    });
+  }
+
+  // Check for multiple canonicals
+  const canonicalCount = $('link[rel="canonical"]').length;
+  if (canonicalCount > 1) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.MULTIPLE_CANONICALS,
+      affectedUrls: [url],
+      details: { count: canonicalCount },
+    });
+  }
+
+  // ==================== H1 CHECKS ====================
+  if (h1s.length === 0) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.H1_MISSING,
+      affectedUrls: [url],
+    });
+  } else if (h1s.length > 1) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.H1_MULTIPLE,
+      affectedUrls: [url],
+      details: { h1s, count: h1s.length },
+    });
+  }
+
+  // Check if H1 duplicates title
+  if (h1s.length === 1 && title && h1s[0].toLowerCase() === title.toLowerCase()) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.H1_DUPLICATE_OF_TITLE,
+      affectedUrls: [url],
+      details: { h1: h1s[0], title },
+    });
+  }
+
+  // Check for missing H2 tags (important for content structure)
+  const h2Count = headings.filter(h => h.level === 2).length;
+  if (h2Count === 0 && wordCount > 100) {
+    // Only warn if there's enough content to warrant H2 headings
+    issues.push({
+      code: 'H2_MISSING',
+      severity: 'warning',
+      category: 'on-page',
+      title: 'No H2 headings found',
+      description: 'No H2 tags were found on the page. H2 headings help structure content and improve readability.',
+      impact: 'Without H2 headings, search engines and users may find it harder to understand content structure. H2s are important for featuring in search results.',
+      howToFix: 'Break your content into logical sections using H2 headings. Include relevant keywords naturally in your H2 tags.',
+      affectedUrls: [url],
+    });
+  }
+
+  // Check heading hierarchy
+  let previousLevel = 0;
+  for (const heading of headings) {
+    if (heading.level > previousLevel + 1 && previousLevel > 0) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.HEADING_SKIP,
+        affectedUrls: [url],
+        details: { from: previousLevel, to: heading.level },
+      });
+      break; // Only report once
+    }
+    previousLevel = heading.level;
+  }
+
+  // ==================== CONTENT CHECKS ====================
+  if (wordCount < 300) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.THIN_CONTENT,
+      affectedUrls: [url],
+      details: { wordCount },
+    });
+  }
+
+  if (textToHtmlRatio < 10) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.LOW_TEXT_HTML_RATIO,
+      affectedUrls: [url],
+      details: { ratio: textToHtmlRatio.toFixed(1) + '%' },
+    });
+  }
+
+  // ==================== NOINDEX CHECK ====================
+  if (hasNoindex) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.NOINDEX_TAG,
+      affectedUrls: [url],
+      details: { metaRobots },
+    });
+  }
+
+  return { issues, data };
+}

package/src/audit/checks/page-resources.ts

@@ -0,0 +1,285 @@
+/**
+ * Page Resources Check (Page Objects Analysis)
+ *
+ * Analyzes the number and types of embedded resources on a page.
+ * Too many HTTP requests slow down page load significantly due to:
+ * - Connection overhead (DNS, TCP, TLS)
+ * - Browser connection limits per domain
+ * - Render blocking
+ *
+ * Best practices:
+ * - Keep total requests under 50 for optimal performance
+ * - Minimize third-party resources
+ * - Combine/bundle CSS and JS where possible
+ */
+
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+
+export interface PageResourcesData {
+  total: number;
+  byType: {
+    stylesheets: number;
+    scripts: number;
+    images: number;
+    fonts: number;
+    iframes: number;
+    other: number;
+  };
+  byOrigin: {
+    firstParty: number;
+    thirdParty: number;
+  };
+  thirdPartyDomains: string[];
+  details: {
+    stylesheets: string[];
+    scripts: string[];
+    images: string[];
+    fonts: string[];
+    iframes: string[];
+  };
+}
+
+/**
+ * Analyze page resources
+ */
+export function analyzePageResources(html: string, url: string): { issues: AuditIssue[]; data: PageResourcesData } {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+  const baseUrl = new URL(url);
+  const baseHostname = baseUrl.hostname;
+
+  const stylesheets: string[] = [];
+  const scripts: string[] = [];
+  const images: string[] = [];
+  const fonts: string[] = [];
+  const iframes: string[] = [];
+  const thirdPartyDomains = new Set<string>();
+
+  let firstParty = 0;
+  let thirdParty = 0;
+
+  /**
+   * Check if URL is first-party
+   */
+  function isFirstParty(resourceUrl: string): boolean {
+    try {
+      const resourceHostname = new URL(resourceUrl, url).hostname;
+      // Consider same domain or subdomains as first-party
+      return resourceHostname === baseHostname || resourceHostname.endsWith(`.${baseHostname}`);
+    } catch {
+      return true; // Relative URLs are first-party
+    }
+  }
+
+  /**
+   * Track resource origin
+   */
+  function trackOrigin(resourceUrl: string): void {
+    if (isFirstParty(resourceUrl)) {
+      firstParty++;
+    } else {
+      thirdParty++;
+      try {
+        const domain = new URL(resourceUrl, url).hostname;
+        thirdPartyDomains.add(domain);
+      } catch {
+        // Invalid URL
+      }
+    }
+  }
+
+  // Extract stylesheets
+  $('link[rel="stylesheet"][href]').each((_, el) => {
+    const href = $(el).attr('href');
+    if (href && !href.startsWith('data:')) {
+      stylesheets.push(href);
+      trackOrigin(href);
+    }
+  });
+
+  // Extract scripts
+  $('script[src]').each((_, el) => {
+    const src = $(el).attr('src');
+    if (src && !src.startsWith('data:')) {
+      scripts.push(src);
+      trackOrigin(src);
+    }
+  });
+
+  // Extract images
+  $('img[src]').each((_, el) => {
+    const src = $(el).attr('src');
+    if (src && !src.startsWith('data:')) {
+      images.push(src);
+      trackOrigin(src);
+    }
+  });
+
+  // Also check srcset for responsive images
+  $('img[srcset], source[srcset]').each((_, el) => {
+    const srcset = $(el).attr('srcset');
+    if (srcset) {
+      // Parse srcset - format: "url1 1x, url2 2x" or "url1 300w, url2 600w"
+      const urls = srcset.split(',').map((s) => s.trim().split(/\s+/)[0]);
+      for (const srcUrl of urls) {
+        if (srcUrl && !srcUrl.startsWith('data:') && !images.includes(srcUrl)) {
+          images.push(srcUrl);
+          trackOrigin(srcUrl);
+        }
+      }
+    }
+  });
+
+  // Extract fonts (preloaded or linked)
+  $('link[rel="preload"][as="font"], link[href*=".woff"], link[href*=".woff2"], link[href*=".ttf"], link[href*=".otf"]').each(
+    (_, el) => {
+      const href = $(el).attr('href');
+      if (href && !href.startsWith('data:')) {
+        fonts.push(href);
+        trackOrigin(href);
+      }
+    }
+  );
+
+  // Extract iframes
+  $('iframe[src]').each((_, el) => {
+    const src = $(el).attr('src');
+    if (src && !src.startsWith('about:') && !src.startsWith('javascript:')) {
+      iframes.push(src);
+      trackOrigin(src);
+    }
+  });
+
+  // Calculate other resources (preloads, prefetches that aren't already counted)
+  let other = 0;
+  $('link[rel="preload"], link[rel="prefetch"], link[rel="modulepreload"]').each((_, el) => {
+    const href = $(el).attr('href');
+    const as = $(el).attr('as');
+    if (href && !href.startsWith('data:')) {
+      // Don't double-count fonts and stylesheets
+      if (as !== 'font' && as !== 'style' && !stylesheets.includes(href) && !fonts.includes(href)) {
+        other++;
+        trackOrigin(href);
+      }
+    }
+  });
+
+  const total = stylesheets.length + scripts.length + images.length + fonts.length + iframes.length + other;
+
+  // Generate issues
+  if (total > 100) {
+    issues.push({
+      code: 'PAGE_RESOURCES_EXCESSIVE',
+      severity: 'error',
+      category: 'performance',
+      title: 'Excessive number of page resources',
+      description: `Page requests ${total} resources. This significantly impacts load time due to connection overhead and browser limits.`,
+      impact:
+        'Too many HTTP requests cause slow page loads, poor Core Web Vitals, and high bounce rates. Each request has DNS, TCP, and TLS overhead.',
+      howToFix:
+        'Combine CSS/JS files, use image sprites or inline small images, lazy-load non-critical resources, remove unused dependencies.',
+      affectedUrls: [url],
+      details: {
+        total,
+        breakdown: {
+          stylesheets: stylesheets.length,
+          scripts: scripts.length,
+          images: images.length,
+          fonts: fonts.length,
+          iframes: iframes.length,
+          other,
+        },
+        recommendation: 'Aim for under 50 total requests for optimal performance.',
+      },
+    });
+  } else if (total > 50) {
+    issues.push({
+      code: 'PAGE_RESOURCES_HIGH',
+      severity: 'warning',
+      category: 'performance',
+      title: 'High number of page resources',
+      description: `Page requests ${total} resources. Consider reducing for better performance.`,
+      impact: 'Many HTTP requests increase page load time, especially on mobile networks.',
+      howToFix: 'Bundle CSS/JS files, lazy-load images below the fold, consider critical CSS inlining.',
+      affectedUrls: [url],
+      details: {
+        total,
+        breakdown: {
+          stylesheets: stylesheets.length,
+          scripts: scripts.length,
+          images: images.length,
+          fonts: fonts.length,
+          iframes: iframes.length,
+          other,
+        },
+      },
+    });
+  }
+
+  // Check third-party resources
+  if (thirdParty > 20) {
+    issues.push({
+      code: 'PAGE_RESOURCES_THIRD_PARTY_HIGH',
+      severity: 'warning',
+      category: 'performance',
+      title: 'Many third-party resources',
+      description: `Page loads ${thirdParty} resources from ${thirdPartyDomains.size} third-party domains.`,
+      impact:
+        'Third-party resources are outside your control and add latency. They can also be a privacy/security concern.',
+      howToFix:
+        'Self-host critical third-party resources when possible. Use preconnect hints for remaining third-party origins.',
+      affectedUrls: [url],
+      details: {
+        thirdPartyCount: thirdParty,
+        domains: Array.from(thirdPartyDomains).slice(0, 10),
+      },
+    });
+  }
+
+  // Check for too many iframes
+  if (iframes.length > 3) {
+    issues.push({
+      code: 'PAGE_RESOURCES_MANY_IFRAMES',
+      severity: 'warning',
+      category: 'performance',
+      title: 'Multiple iframes detected',
+      description: `Page contains ${iframes.length} iframes. Each iframe loads its own document and resources.`,
+      impact: 'Iframes significantly increase page weight and can block the main thread.',
+      howToFix:
+        'Lazy-load iframes that are below the fold. Consider native embeds or facade patterns for video/widget iframes.',
+      affectedUrls: [url],
+      details: {
+        iframeCount: iframes.length,
+        iframes: iframes.slice(0, 5),
+      },
+    });
+  }
+
+  return {
+    issues,
+    data: {
+      total,
+      byType: {
+        stylesheets: stylesheets.length,
+        scripts: scripts.length,
+        images: images.length,
+        fonts: fonts.length,
+        iframes: iframes.length,
+        other,
+      },
+      byOrigin: {
+        firstParty,
+        thirdParty,
+      },
+      thirdPartyDomains: Array.from(thirdPartyDomains),
+      details: {
+        stylesheets,
+        scripts,
+        images: images.slice(0, 20), // Limit for data size
+        fonts,
+        iframes,
+      },
+    },
+  };
+}

package/src/audit/checks/pagination.ts

@@ -0,0 +1,180 @@
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+import { ISSUE_DEFINITIONS } from '../types.js';
+
+export interface PaginationData {
+  hasPagination: boolean;
+  hasHtmlPaginationLinks: boolean;
+  hasInfiniteScroll: boolean;
+  hasLoadMoreButton: boolean;
+  paginationLinks: string[];
+  relNextPrev: {
+    hasNext: boolean;
+    hasPrev: boolean;
+    nextUrl?: string;
+    prevUrl?: string;
+  };
+  currentPage?: number;
+  totalPages?: number;
+}
+
+export function analyzePagination(
+  html: string,
+  url: string,
+  canonical?: string
+): { issues: AuditIssue[]; data: PaginationData } {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+
+  // Check for rel="next" and rel="prev"
+  const nextLink = $('link[rel="next"]').attr('href');
+  const prevLink = $('link[rel="prev"]').attr('href');
+
+  // Detect pagination patterns in links
+  const paginationLinks: string[] = [];
+  const paginationPatterns = [
+    /[?&]page=\d+/,
+    /[?&]p=\d+/,
+    /\/page\/\d+/,
+    /\/p\/\d+/,
+    /-page-\d+/,
+    /\/\d+\/?$/,
+  ];
+
+  $('a[href]').each((_, el) => {
+    const href = $(el).attr('href') || '';
+    for (const pattern of paginationPatterns) {
+      if (pattern.test(href)) {
+        try {
+          const fullUrl = new URL(href, url).href;
+          if (!paginationLinks.includes(fullUrl)) {
+            paginationLinks.push(fullUrl);
+          }
+        } catch {
+          // Invalid URL, skip
+        }
+        break;
+      }
+    }
+  });
+
+  // Detect infinite scroll patterns
+  const hasInfiniteScrollScript = html.includes('infinite-scroll') ||
+    html.includes('infiniteScroll') ||
+    html.includes('infinite_scroll') ||
+    $('[data-infinite-scroll]').length > 0 ||
+    $('[data-infinite]').length > 0 ||
+    $('.infinite-scroll').length > 0;
+
+  // Detect "load more" buttons
+  const loadMoreSelectors = [
+    'button:contains("Load More")',
+    'button:contains("Load more")',
+    'button:contains("Show More")',
+    'button:contains("Show more")',
+    'a:contains("Load More")',
+    'a:contains("Load more")',
+    '[class*="load-more"]',
+    '[class*="loadmore"]',
+    '[data-load-more]',
+  ];
+
+  let hasLoadMoreButton = false;
+  for (const selector of loadMoreSelectors) {
+    try {
+      if ($(selector).length > 0) {
+        hasLoadMoreButton = true;
+        break;
+      }
+    } catch {
+      // Invalid selector, skip
+    }
+  }
+
+  // Try to detect current page number
+  let currentPage: number | undefined;
+  let totalPages: number | undefined;
+
+  // Check URL for page number
+  const pageMatch = url.match(/[?&]page=(\d+)|\/page\/(\d+)|[?&]p=(\d+)/);
+  if (pageMatch) {
+    currentPage = parseInt(pageMatch[1] || pageMatch[2] || pageMatch[3], 10);
+  }
+
+  // Check for "Page X of Y" pattern
+  const pageOfPattern = /page\s*(\d+)\s*of\s*(\d+)/i;
+  const pageOfMatch = $('body').text().match(pageOfPattern);
+  if (pageOfMatch) {
+    currentPage = parseInt(pageOfMatch[1], 10);
+    totalPages = parseInt(pageOfMatch[2], 10);
+  }
+
+  const hasPagination = paginationLinks.length > 0 ||
+    nextLink !== undefined ||
+    prevLink !== undefined ||
+    currentPage !== undefined;
+
+  const hasHtmlPaginationLinks = paginationLinks.length > 0;
+
+  const data: PaginationData = {
+    hasPagination,
+    hasHtmlPaginationLinks,
+    hasInfiniteScroll: hasInfiniteScrollScript,
+    hasLoadMoreButton,
+    paginationLinks,
+    relNextPrev: {
+      hasNext: !!nextLink,
+      hasPrev: !!prevLink,
+      nextUrl: nextLink,
+      prevUrl: prevLink,
+    },
+    currentPage,
+    totalPages,
+  };
+
+  // ==================== Issue Detection ====================
+
+  // Infinite scroll without HTML fallback links
+  if (hasInfiniteScrollScript && !hasHtmlPaginationLinks) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.INFINITE_SCROLL_NO_FALLBACK,
+      affectedUrls: [url],
+      details: {
+        hasLoadMore: hasLoadMoreButton,
+        suggestion: 'Add <a href> pagination links alongside infinite scroll for SEO',
+      },
+    });
+  }
+
+  // Load more without HTML links
+  if (hasLoadMoreButton && !hasHtmlPaginationLinks && !hasInfiniteScrollScript) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.PAGINATION_NO_LINKS,
+      affectedUrls: [url],
+      details: {
+        suggestion: 'Ensure "Load More" button also has underlying <a> links',
+      },
+    });
+  }
+
+  // Check for improper canonical on paginated pages
+  if (hasPagination && currentPage && currentPage > 1 && canonical) {
+    // Check if canonical points to page 1
+    const isCanonicalToPage1 = !paginationPatterns.some(p => p.test(canonical));
+    const urlHasPageNumber = paginationPatterns.some(p => p.test(url));
+
+    if (isCanonicalToPage1 && urlHasPageNumber) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.PAGINATION_CANONICAL_ISSUE,
+        affectedUrls: [url],
+        details: {
+          currentPage,
+          canonical,
+          suggestion: 'Paginated pages should self-reference or point to a View All page',
+        },
+      });
+    }
+  }
+
+  return { issues, data };
+}