@rankcli/agent-runtime 0.0.1

package/src/audit/checks/redirect-analysis.ts

@@ -0,0 +1,153 @@
+import { httpHead } from '../../utils/http.js';
+import type { AuditIssue } from '../types.js';
+import { ISSUE_DEFINITIONS } from '../types.js';
+
+export interface RedirectData {
+  hasRedirect: boolean;
+  redirectChain: RedirectHop[];
+  isLoop: boolean;
+  finalUrl?: string;
+  totalHops: number;
+}
+
+export interface RedirectHop {
+  url: string;
+  statusCode: number;
+  location?: string;
+}
+
+export async function analyzeRedirects(
+  url: string,
+  maxHops: number = 10
+): Promise<{ issues: AuditIssue[]; data: RedirectData }> {
+  const issues: AuditIssue[] = [];
+  const chain: RedirectHop[] = [];
+  const visitedUrls = new Set<string>();
+  let currentUrl = url;
+  let isLoop = false;
+
+  while (chain.length < maxHops) {
+    // Check for loop
+    if (visitedUrls.has(currentUrl)) {
+      isLoop = true;
+      break;
+    }
+    visitedUrls.add(currentUrl);
+
+    try {
+      const response = await httpHead(currentUrl, {
+        timeout: 5000,
+        maxRedirects: 0,
+        validateStatus: () => true,
+      });
+
+      const hop: RedirectHop = {
+        url: currentUrl,
+        statusCode: response.status,
+      };
+
+      if (response.status >= 300 && response.status < 400) {
+        const location = response.headers['location'];
+        if (location) {
+          hop.location = location;
+          chain.push(hop);
+          currentUrl = new URL(location, currentUrl).href;
+          continue;
+        }
+      }
+
+      chain.push(hop);
+      break;
+    } catch (error) {
+      chain.push({
+        url: currentUrl,
+        statusCode: 0,
+      });
+      break;
+    }
+  }
+
+  const hasRedirect = chain.length > 1;
+  const finalUrl = chain.length > 0 ? chain[chain.length - 1].url : url;
+
+  const data: RedirectData = {
+    hasRedirect,
+    redirectChain: chain,
+    isLoop,
+    finalUrl,
+    totalHops: chain.length - 1,
+  };
+
+  // ==================== Issue Detection ====================
+
+  // Redirect loop
+  if (isLoop) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.REDIRECT_LOOP,
+      affectedUrls: [url],
+      details: {
+        chain: chain.map(h => `${h.url} (${h.statusCode})`),
+      },
+    });
+  }
+
+  // Redirect chain (more than one redirect)
+  if (!isLoop && chain.length > 2) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.REDIRECT_CHAIN,
+      affectedUrls: [url],
+      details: {
+        chain: chain.map(h => `${h.url} (${h.statusCode})`),
+        hops: chain.length - 1,
+        finalUrl,
+      },
+    });
+  }
+
+  return { issues, data };
+}
+
+// Check internal links for redirect targets
+export async function checkInternalRedirects(
+  internalLinks: string[],
+  batchSize: number = 10
+): Promise<{ redirectLinks: Array<{ source: string; target: string; statusCode: number }> }> {
+  const redirectLinks: Array<{ source: string; target: string; statusCode: number }> = [];
+
+  // Process in batches to avoid overwhelming the server
+  for (let i = 0; i < internalLinks.length; i += batchSize) {
+    const batch = internalLinks.slice(i, i + batchSize);
+    const promises = batch.map(async (link) => {
+      try {
+        const response = await httpHead(link, {
+          timeout: 5000,
+          maxRedirects: 0,
+          validateStatus: () => true,
+        });
+
+        if (response.status >= 300 && response.status < 400) {
+          const location = response.headers['location'];
+          if (location) {
+            return {
+              source: link,
+              target: new URL(location, link).href,
+              statusCode: response.status,
+            };
+          }
+        }
+        return null;
+      } catch {
+        return null;
+      }
+    });
+
+    const results = await Promise.all(promises);
+    for (const result of results) {
+      if (result) {
+        redirectLinks.push(result);
+      }
+    }
+  }
+
+  return { redirectLinks };
+}

package/src/audit/checks/redirect-chain.ts

@@ -0,0 +1,389 @@
+// Redirect Chain Detection - Multiple redirects hurt SEO
+// Reference: "Technical SEO for Developers - 17 Tips to Rank Higher"
+// "Managing redirects... Broken links can absolutely tank your SEO numbers"
+
+import { httpGet } from '../../utils/http.js';
+import type { AuditIssue } from '../types.js';
+
+export interface RedirectHop {
+  url: string;
+  statusCode: number;
+  statusText: string;
+  redirectTo: string | null;
+  responseTime: number;
+}
+
+export interface RedirectChainResult {
+  originalUrl: string;
+  finalUrl: string;
+  hops: RedirectHop[];
+  chainLength: number;
+  totalTime: number;
+  hasHttpsUpgrade: boolean;
+  hasWwwNormalization: boolean;
+  hasTrailingSlashIssue: boolean;
+  isInternalLoop: boolean;
+  issues: string[];
+}
+
+// Maximum redirects to follow before giving up
+const MAX_REDIRECTS = 10;
+
+/**
+ * Follow redirects and build the chain
+ */
+export async function traceRedirectChain(
+  url: string,
+  options: { timeout?: number } = {}
+): Promise<RedirectChainResult> {
+  const hops: RedirectHop[] = [];
+  let currentUrl = url;
+  let chainLength = 0;
+  let totalTime = 0;
+  const visitedUrls = new Set<string>();
+
+  const timeout = options.timeout || 10000;
+
+  while (chainLength < MAX_REDIRECTS) {
+    // Detect loops
+    if (visitedUrls.has(currentUrl)) {
+      break;
+    }
+    visitedUrls.add(currentUrl);
+
+    try {
+      const startTime = Date.now();
+
+      const response = await httpGet<string>(currentUrl, {
+        
+        timeout,
+        maxRedirects: 0, // Don't auto-follow, we want to trace manually
+        validateStatus: () => true, // Accept all status codes
+      });
+
+      const responseTime = Date.now() - startTime;
+      totalTime += responseTime;
+
+      const statusCode = response.status;
+      const locationHeader = response.headers.location;
+
+      // Normalize the redirect location
+      let redirectTo: string | null = null;
+      if (locationHeader) {
+        try {
+          // Handle relative URLs
+          redirectTo = new URL(locationHeader, currentUrl).toString();
+        } catch {
+          redirectTo = locationHeader;
+        }
+      }
+
+      hops.push({
+        url: currentUrl,
+        statusCode,
+        statusText: response.statusText || getStatusText(statusCode),
+        redirectTo,
+        responseTime,
+      });
+
+      // Check if this is a redirect
+      if (statusCode >= 300 && statusCode < 400 && redirectTo) {
+        chainLength++;
+        currentUrl = redirectTo;
+      } else {
+        // Final destination reached
+        break;
+      }
+    } catch (error) {
+      // Network error or timeout
+      hops.push({
+        url: currentUrl,
+        statusCode: 0,
+        statusText: error instanceof Error ? error.message : 'Network error',
+        redirectTo: null,
+        responseTime: 0,
+      });
+      break;
+    }
+  }
+
+  const finalUrl = hops.length > 0 ? hops[hops.length - 1].url : url;
+
+  // Analyze the chain for common issues
+  const issues = analyzeChainIssues(url, hops);
+
+  return {
+    originalUrl: url,
+    finalUrl,
+    hops,
+    chainLength: hops.length - 1, // Number of redirects (not including final destination)
+    totalTime,
+    hasHttpsUpgrade: detectHttpsUpgrade(hops),
+    hasWwwNormalization: detectWwwNormalization(hops),
+    hasTrailingSlashIssue: detectTrailingSlashIssue(hops),
+    isInternalLoop: visitedUrls.size !== hops.length,
+    issues,
+  };
+}
+
+function getStatusText(code: number): string {
+  const statusTexts: Record<number, string> = {
+    200: 'OK',
+    301: 'Moved Permanently',
+    302: 'Found',
+    303: 'See Other',
+    307: 'Temporary Redirect',
+    308: 'Permanent Redirect',
+    404: 'Not Found',
+    500: 'Internal Server Error',
+  };
+  return statusTexts[code] || 'Unknown';
+}
+
+function detectHttpsUpgrade(hops: RedirectHop[]): boolean {
+  for (let i = 0; i < hops.length - 1; i++) {
+    const current = hops[i].url;
+    const next = hops[i].redirectTo;
+    if (current.startsWith('http://') && next?.startsWith('https://')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function detectWwwNormalization(hops: RedirectHop[]): boolean {
+  for (let i = 0; i < hops.length - 1; i++) {
+    const currentHost = extractHost(hops[i].url);
+    const nextHost = hops[i].redirectTo ? extractHost(hops[i].redirectTo!) : null;
+
+    if (currentHost && nextHost) {
+      const hasWwwChange =
+        (currentHost.startsWith('www.') && !nextHost.startsWith('www.')) ||
+        (!currentHost.startsWith('www.') && nextHost.startsWith('www.'));
+      if (hasWwwChange) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function detectTrailingSlashIssue(hops: RedirectHop[]): boolean {
+  for (let i = 0; i < hops.length - 1; i++) {
+    const current = new URL(hops[i].url);
+    const next = hops[i].redirectTo ? new URL(hops[i].redirectTo!) : null;
+
+    if (next && current.pathname !== next.pathname) {
+      const pathDiff =
+        (current.pathname.endsWith('/') && !next.pathname.endsWith('/')) ||
+        (!current.pathname.endsWith('/') && next.pathname.endsWith('/'));
+
+      // Check if only difference is trailing slash
+      const normalizedCurrent = current.pathname.replace(/\/$/, '');
+      const normalizedNext = next.pathname.replace(/\/$/, '');
+
+      if (pathDiff && normalizedCurrent === normalizedNext) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function extractHost(url: string): string | null {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return null;
+  }
+}
+
+function analyzeChainIssues(originalUrl: string, hops: RedirectHop[]): string[] {
+  const issues: string[] = [];
+
+  // Check for redirect chain
+  const redirectCount = hops.filter(h => h.statusCode >= 300 && h.statusCode < 400).length;
+  if (redirectCount > 1) {
+    issues.push(`Redirect chain detected: ${redirectCount} hops`);
+  }
+
+  // Check for mixed 301/302
+  const has301 = hops.some(h => h.statusCode === 301 || h.statusCode === 308);
+  const has302 = hops.some(h => h.statusCode === 302 || h.statusCode === 307);
+  if (has301 && has302) {
+    issues.push('Mixed permanent and temporary redirects');
+  }
+
+  // Check for 302 being used where 301 should be
+  const uses302 = hops.some(h => h.statusCode === 302);
+  if (uses302 && redirectCount === 1) {
+    issues.push('Consider using 301 (permanent) instead of 302 (temporary)');
+  }
+
+  // Check for slow redirects
+  for (const hop of hops) {
+    if (hop.responseTime > 500) {
+      issues.push(`Slow redirect: ${hop.url} took ${hop.responseTime}ms`);
+    }
+  }
+
+  // Check for HTTP to HTTPS upgrade in chain
+  if (originalUrl.startsWith('http://')) {
+    const finalHop = hops[hops.length - 1];
+    if (finalHop && !finalHop.url.startsWith('https://')) {
+      issues.push('HTTP URL does not redirect to HTTPS');
+    }
+  }
+
+  // Check for unnecessary www/non-www redirect
+  const httpAndWwwRedirects = hops.filter(h =>
+    h.statusCode >= 300 && h.statusCode < 400
+  );
+  if (httpAndWwwRedirects.length > 1) {
+    issues.push('Multiple normalizations (consider combining HTTPS + www redirects)');
+  }
+
+  return issues;
+}
+
+/**
+ * Main function: Analyze redirects for SEO issues
+ */
+export async function analyzeRedirectChain(
+  url: string
+): Promise<{ issues: AuditIssue[]; data: RedirectChainResult }> {
+  const issues: AuditIssue[] = [];
+  const result = await traceRedirectChain(url);
+
+  // Critical: Redirect loop detected
+  if (result.isInternalLoop) {
+    issues.push({
+      code: 'REDIRECT_LOOP',
+      severity: 'error',
+      category: 'crawlability',
+      title: 'Redirect loop detected',
+      description: 'The URL redirects to itself or creates a circular redirect chain.',
+      impact: 'Search engines cannot index pages with redirect loops. Users will see an error.',
+      howToFix: 'Review redirect rules and ensure each URL points to a single final destination.',
+      affectedUrls: [url],
+      details: {
+        chain: result.hops.map(h => h.url),
+      },
+    });
+  }
+
+  // Error: Long redirect chain (3+ hops)
+  if (result.chainLength >= 3) {
+    issues.push({
+      code: 'LONG_REDIRECT_CHAIN',
+      severity: 'error',
+      category: 'crawlability',
+      title: `Long redirect chain (${result.chainLength} hops)`,
+      description: `URL requires ${result.chainLength} redirects before reaching the final destination.`,
+      impact: 'Long redirect chains slow page load, waste crawl budget, and may lose link equity.',
+      howToFix: 'Update internal links to point directly to the final URL. Combine redirect rules.',
+      affectedUrls: [url],
+      details: {
+        chain: result.hops.map(h => ({ url: h.url, status: h.statusCode })),
+        totalTime: result.totalTime,
+      },
+    });
+  }
+  // Warning: Redirect chain (2 hops)
+  else if (result.chainLength === 2) {
+    issues.push({
+      code: 'REDIRECT_CHAIN',
+      severity: 'warning',
+      category: 'crawlability',
+      title: 'Redirect chain detected (2 hops)',
+      description: 'URL has an intermediate redirect before reaching the final destination.',
+      impact: 'Each redirect adds latency and may dilute link equity slightly.',
+      howToFix: 'Combine redirects into a single hop from source to final destination.',
+      affectedUrls: [url],
+      details: {
+        chain: result.hops.map(h => ({ url: h.url, status: h.statusCode })),
+      },
+    });
+  }
+
+  // Warning: Temporary redirect (302) used
+  const uses302 = result.hops.some(h => h.statusCode === 302 || h.statusCode === 307);
+  if (uses302 && result.chainLength > 0) {
+    issues.push({
+      code: 'TEMPORARY_REDIRECT',
+      severity: 'warning',
+      category: 'crawlability',
+      title: 'Temporary redirect (302/307) used',
+      description: 'URL uses a temporary redirect instead of a permanent redirect.',
+      impact: 'Temporary redirects may not pass full link equity. Use 301/308 for permanent moves.',
+      howToFix: 'Change 302/307 redirects to 301/308 if the redirect is permanent.',
+      affectedUrls: [url],
+      details: {
+        redirectType: result.hops.find(h => h.statusCode === 302 || h.statusCode === 307)?.statusCode,
+      },
+    });
+  }
+
+  // Notice: HTTPS upgrade happening
+  if (result.hasHttpsUpgrade && result.chainLength === 1) {
+    // This is expected and not an issue, but we note it
+  }
+
+  // Notice: Inefficient www normalization
+  if (result.hasWwwNormalization && result.hasHttpsUpgrade && result.chainLength > 1) {
+    issues.push({
+      code: 'INEFFICIENT_NORMALIZATION',
+      severity: 'notice',
+      category: 'crawlability',
+      title: 'Inefficient HTTP/www normalization',
+      description: 'Multiple redirects for HTTPS upgrade and www normalization that could be combined.',
+      impact: 'Extra redirect adds unnecessary latency and server load.',
+      howToFix: 'Configure server to redirect directly from http://domain to https://www.domain (or vice versa) in one hop.',
+      affectedUrls: [url],
+    });
+  }
+
+  // Notice: Slow redirect chain
+  if (result.totalTime > 1000 && result.chainLength > 0) {
+    issues.push({
+      code: 'SLOW_REDIRECTS',
+      severity: 'notice',
+      category: 'performance',
+      title: `Slow redirect chain (${result.totalTime}ms total)`,
+      description: `Redirect chain took ${result.totalTime}ms to complete.`,
+      impact: 'Slow redirects negatively impact Time to First Byte and user experience.',
+      howToFix: 'Optimize server response times and reduce redirect chain length.',
+      affectedUrls: [url],
+      details: {
+        totalTime: result.totalTime,
+        hops: result.hops.map(h => ({ url: h.url, time: h.responseTime })),
+      },
+    });
+  }
+
+  return { issues, data: result };
+}
+
+/**
+ * Batch check multiple URLs for redirect chains
+ */
+export async function batchAnalyzeRedirects(
+  urls: string[]
+): Promise<Map<string, RedirectChainResult>> {
+  const results = new Map<string, RedirectChainResult>();
+
+  // Process in parallel with concurrency limit
+  const concurrency = 5;
+  for (let i = 0; i < urls.length; i += concurrency) {
+    const batch = urls.slice(i, i + concurrency);
+    const batchResults = await Promise.all(
+      batch.map(url => traceRedirectChain(url).then(result => ({ url, result })))
+    );
+
+    for (const { url, result } of batchResults) {
+      results.set(url, result);
+    }
+  }
+
+  return results;
+}