@rankcli/agent-runtime 0.0.14 → 0.0.16

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

@@ -1,285 +0,0 @@
-/**
- * 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

@@ -1,180 +0,0 @@
-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 };
-}

package/src/audit/checks/performance.ts

@@ -1,153 +0,0 @@
-import { httpGet, httpPost } from '../../utils/http.js';
-import type { AuditIssue } from '../types.js';
-import { ISSUE_DEFINITIONS } from '../types.js';
-
-export interface PerformanceData {
-  loadTime: number; // ms
-  ttfb: number; // ms
-  htmlSize: number; // bytes
-  compressed: boolean;
-  cacheControl?: string;
-  contentEncoding?: string;
-}
-
-export async function analyzePerformance(url: string): Promise<{ issues: AuditIssue[]; data: PerformanceData }> {
-  const issues: AuditIssue[] = [];
-
-  const startTime = Date.now();
-
-  try {
-    const response = await httpGet<string>(url, {
-      headers: {
-        'Accept-Encoding': 'gzip, deflate, br',
-      },
-      timeout: 30000,
-      validateStatus: () => true,
-    });
-
-    const loadTime = Date.now() - startTime;
-    // Note: TTFB approximation - fetch doesn't expose this directly
-    const ttfbTime = Math.min(loadTime, loadTime * 0.3); // Estimate ~30% of total
-    const htmlSize = typeof response.data === 'string' ? response.data.length : 0;
-    const contentEncoding = response.headers['content-encoding'];
-    const cacheControl = response.headers['cache-control'];
-    const compressed = !!contentEncoding && ['gzip', 'deflate', 'br'].some(e => contentEncoding.includes(e));
-
-    const data: PerformanceData = {
-      loadTime,
-      ttfb: ttfbTime || loadTime,
-      htmlSize,
-      compressed,
-      cacheControl,
-      contentEncoding,
-    };
-
-    // Check load time
-    if (loadTime > 3000) {
-      issues.push({
-        ...ISSUE_DEFINITIONS.SLOW_PAGE,
-        affectedUrls: [url],
-        details: { loadTime: `${(loadTime / 1000).toFixed(1)}s` },
-      });
-    }
-
-    // Check TTFB
-    if (ttfbTime > 600) {
-      issues.push({
-        ...ISSUE_DEFINITIONS.SLOW_TTFB,
-        affectedUrls: [url],
-        details: { ttfb: `${ttfbTime}ms` },
-      });
-    }
-
-    // Check HTML size
-    if (htmlSize > 100 * 1024) { // > 100KB
-      issues.push({
-        ...ISSUE_DEFINITIONS.HTML_TOO_LARGE,
-        affectedUrls: [url],
-        details: { size: `${(htmlSize / 1024).toFixed(0)}KB` },
-      });
-    }
-
-    // Check compression
-    if (!compressed && htmlSize > 1024) {
-      issues.push({
-        ...ISSUE_DEFINITIONS.UNCOMPRESSED,
-        affectedUrls: [url],
-        details: { htmlSize: `${(htmlSize / 1024).toFixed(0)}KB` },
-      });
-    }
-
-    // Check cache headers
-    if (!cacheControl) {
-      issues.push({
-        ...ISSUE_DEFINITIONS.NO_CACHE,
-        affectedUrls: [url],
-      });
-    }
-
-    return { issues, data };
-  } catch (error) {
-    return {
-      issues: [{
-        ...ISSUE_DEFINITIONS.SLOW_PAGE,
-        affectedUrls: [url],
-        details: { error: error instanceof Error ? error.message : 'Request failed' },
-      }],
-      data: {
-        loadTime: 0,
-        ttfb: 0,
-        htmlSize: 0,
-        compressed: false,
-      }
-    };
-  }
-}
-
-// Fetch Core Web Vitals from CrUX API (requires API key)
-export async function fetchCoreWebVitals(url: string, apiKey?: string): Promise<{
-  lcp?: { value: number; rating: 'good' | 'needs-improvement' | 'poor' };
-  fid?: { value: number; rating: 'good' | 'needs-improvement' | 'poor' };
-  cls?: { value: number; rating: 'good' | 'needs-improvement' | 'poor' };
-  inp?: { value: number; rating: 'good' | 'needs-improvement' | 'poor' };
-} | null> {
-  if (!apiKey) return null;
-
-  try {
-    const response = await httpPost<{ record?: { metrics?: Record<string, { percentiles?: { p75?: number } }> } }>(
-      `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${apiKey}`,
-      { url },
-      { timeout: 10000 }
-    );
-
-    const metrics = response.data?.record?.metrics;
-    if (!metrics) return null;
-
-    const getRating = (value: number, thresholds: [number, number]): 'good' | 'needs-improvement' | 'poor' => {
-      if (value <= thresholds[0]) return 'good';
-      if (value <= thresholds[1]) return 'needs-improvement';
-      return 'poor';
-    };
-
-    return {
-      lcp: metrics.largest_contentful_paint?.percentiles?.p75 ? {
-        value: metrics.largest_contentful_paint.percentiles.p75,
-        rating: getRating(metrics.largest_contentful_paint.percentiles.p75, [2500, 4000]),
-      } : undefined,
-      fid: metrics.first_input_delay?.percentiles?.p75 ? {
-        value: metrics.first_input_delay.percentiles.p75,
-        rating: getRating(metrics.first_input_delay.percentiles.p75, [100, 300]),
-      } : undefined,
-      cls: metrics.cumulative_layout_shift?.percentiles?.p75 ? {
-        value: metrics.cumulative_layout_shift.percentiles.p75,
-        rating: getRating(metrics.cumulative_layout_shift.percentiles.p75, [0.1, 0.25]),
-      } : undefined,
-      inp: metrics.interaction_to_next_paint?.percentiles?.p75 ? {
-        value: metrics.interaction_to_next_paint.percentiles.p75,
-        rating: getRating(metrics.interaction_to_next_paint.percentiles.p75, [200, 500]),
-      } : undefined,
-    };
-  } catch {
-    return null;
-  }
-}