@rankcli/agent-runtime 0.0.1

package/src/audit/checks/llms-txt.ts

@@ -0,0 +1,224 @@
+/**
+ * llms.txt Check
+ *
+ * llms.txt is a proposed standard (https://llmstxt.org/) for providing
+ * context to Large Language Models about a website.
+ *
+ * The file is a Markdown document at /llms.txt that contains:
+ * - Brief description of the site/organization
+ * - Links to important pages
+ * - Optional detailed content at /llms-full.txt
+ *
+ * Format:
+ * # Site Name
+ * > Brief description
+ *
+ * ## Section
+ * - [Link Text](url): Description
+ */
+
+import { httpGet } from '../../utils/http.js';
+import type { AuditIssue } from '../types.js';
+
+export interface LlmsTxtData {
+  exists: boolean;
+  fullVersionExists: boolean;
+  content?: string;
+  structure: {
+    hasTitle: boolean;
+    hasDescription: boolean;
+    hasSections: boolean;
+    hasLinks: boolean;
+    linkCount: number;
+  };
+  contentLength: number;
+}
+
+export async function analyzeLlmsTxt(
+  url: string
+): Promise<{ issues: AuditIssue[]; data: LlmsTxtData }> {
+  const issues: AuditIssue[] = [];
+  const parsedUrl = new URL(url);
+  const baseUrl = parsedUrl.origin;
+
+  // Check for llms.txt
+  const llmsTxtUrl = new URL('/llms.txt', baseUrl).href;
+  const llmsFullUrl = new URL('/llms-full.txt', baseUrl).href;
+
+  let exists = false;
+  let fullVersionExists = false;
+  let content: string | undefined;
+  let structure = {
+    hasTitle: false,
+    hasDescription: false,
+    hasSections: false,
+    hasLinks: false,
+    linkCount: 0,
+  };
+  let contentLength = 0;
+
+  try {
+    // Check main llms.txt
+    const response = await httpGet<string>(llmsTxtUrl, {
+      timeout: 10000,
+      validateStatus: () => true,
+    });
+
+    if (response.status === 200) {
+      exists = true;
+      content = response.data as string;
+      contentLength = content.length;
+      structure = analyzeStructure(content);
+    }
+
+    // Check for full version
+    const fullResponse = await httpGet<string>(llmsFullUrl, {
+      timeout: 10000,
+      validateStatus: () => true,
+    });
+
+    if (fullResponse.status === 200) {
+      fullVersionExists = true;
+    }
+  } catch {
+    // Network error, treat as not existing
+  }
+
+  // Generate issues
+  if (!exists) {
+    issues.push({
+      code: 'AI_NO_LLMS_TXT',
+      severity: 'notice',
+      category: 'ai-readiness',
+      title: 'No llms.txt file found',
+      description: 'llms.txt is a proposed standard for providing context to LLMs about your website. Having one helps AI systems better understand and represent your site.',
+      impact: 'AI systems may have less context about your site, potentially leading to less accurate representations.',
+      howToFix: 'Create an /llms.txt file with a Markdown description of your site. Include: site name, brief description, and links to key pages. See https://llmstxt.org/ for the specification.',
+      affectedUrls: [llmsTxtUrl],
+      details: {
+        specification: 'https://llmstxt.org/',
+        exampleFormat: `# Site Name
+
+> Brief description of your site
+
+## About
+- [About Us](/about): Learn more about our company
+
+## Products
+- [Product A](/products/a): Description of product A
+- [Product B](/products/b): Description of product B
+
+## Documentation
+- [Docs](/docs): Full documentation`,
+      },
+    });
+  } else {
+    // Check structure quality
+    if (!structure.hasTitle) {
+      issues.push({
+        code: 'AI_LLMS_TXT_NO_TITLE',
+        severity: 'notice',
+        category: 'ai-readiness',
+        title: 'llms.txt missing title heading',
+        description: 'Your llms.txt file should start with a # heading containing your site/organization name.',
+        impact: 'LLMs may not properly identify your site.',
+        howToFix: 'Add a title heading at the top: # Your Site Name',
+        affectedUrls: [llmsTxtUrl],
+      });
+    }
+
+    if (!structure.hasDescription) {
+      issues.push({
+        code: 'AI_LLMS_TXT_NO_DESCRIPTION',
+        severity: 'notice',
+        category: 'ai-readiness',
+        title: 'llms.txt missing description',
+        description: 'Your llms.txt should include a brief description (blockquote starting with >) explaining what your site/organization does.',
+        impact: 'LLMs may not understand your site\'s purpose.',
+        howToFix: 'Add a description blockquote after the title: > Brief description of your site',
+        affectedUrls: [llmsTxtUrl],
+      });
+    }
+
+    if (!structure.hasLinks || structure.linkCount < 3) {
+      issues.push({
+        code: 'AI_LLMS_TXT_FEW_LINKS',
+        severity: 'notice',
+        category: 'ai-readiness',
+        title: 'llms.txt has few navigation links',
+        description: `Your llms.txt only has ${structure.linkCount} link(s). Include links to your most important pages to help LLMs navigate your content.`,
+        impact: 'LLMs may miss important content on your site.',
+        howToFix: 'Add more links in Markdown format: - [Page Title](/path): Brief description',
+        affectedUrls: [llmsTxtUrl],
+      });
+    }
+
+    if (contentLength < 200) {
+      issues.push({
+        code: 'AI_LLMS_TXT_TOO_SHORT',
+        severity: 'notice',
+        category: 'ai-readiness',
+        title: 'llms.txt content is very short',
+        description: `Your llms.txt is only ${contentLength} characters. Consider adding more context about your site.`,
+        impact: 'LLMs may not have enough context to properly represent your site.',
+        howToFix: 'Expand your llms.txt with more sections, descriptions, and links to key content.',
+        affectedUrls: [llmsTxtUrl],
+      });
+    }
+  }
+
+  return {
+    issues,
+    data: {
+      exists,
+      fullVersionExists,
+      content: content?.substring(0, 1000), // Truncate for data
+      structure,
+      contentLength,
+    },
+  };
+}
+
+function analyzeStructure(content: string): LlmsTxtData['structure'] {
+  const lines = content.split('\n');
+
+  let hasTitle = false;
+  let hasDescription = false;
+  let hasSections = false;
+  let hasLinks = false;
+  let linkCount = 0;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Check for title (# heading at start)
+    if (trimmed.startsWith('# ') && !trimmed.startsWith('## ')) {
+      hasTitle = true;
+    }
+
+    // Check for description (blockquote)
+    if (trimmed.startsWith('>')) {
+      hasDescription = true;
+    }
+
+    // Check for sections (## headings)
+    if (trimmed.startsWith('## ')) {
+      hasSections = true;
+    }
+
+    // Check for Markdown links
+    const linkMatches = trimmed.match(/\[([^\]]+)\]\(([^)]+)\)/g);
+    if (linkMatches) {
+      hasLinks = true;
+      linkCount += linkMatches.length;
+    }
+  }
+
+  return {
+    hasTitle,
+    hasDescription,
+    hasSections,
+    hasLinks,
+    linkCount,
+  };
+}

package/src/audit/checks/local-seo.ts

@@ -0,0 +1,296 @@
+// Local SEO Checks
+// Checks for LocalBusiness schema, NAP consistency, address/phone detection
+
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+import { ISSUE_DEFINITIONS } from '../types.js';
+
+// Phone number patterns
+const PHONE_PATTERNS = [
+  /\+?1?[-.\s]?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}/g, // US/Canada
+  /\+?[0-9]{1,3}[-.\s]?[0-9]{2,4}[-.\s]?[0-9]{3,4}[-.\s]?[0-9]{3,4}/g, // International
+  /\b[0-9]{3}[-.\s][0-9]{3}[-.\s][0-9]{4}\b/g, // Simple US format
+];
+
+// Address patterns (simplified)
+const ADDRESS_PATTERNS = [
+  /\d+\s+[\w\s]+(?:street|st|avenue|ave|road|rd|boulevard|blvd|drive|dr|lane|ln|way|court|ct|circle|cir|place|pl)[\s,]+[\w\s]+,?\s*(?:AL|AK|AZ|AR|CA|CO|CT|DE|FL|GA|HI|ID|IL|IN|IA|KS|KY|LA|ME|MD|MA|MI|MN|MS|MO|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PA|RI|SC|SD|TN|TX|UT|VT|VA|WA|WV|WI|WY)\s*\d{5}/gi,
+  /\d+\s+[\w\s]+,\s*[\w\s]+,\s*[A-Z]{2}\s*\d{5}/gi, // Generic US address
+];
+
+export interface LocalSEOData {
+  hasLocalBusinessSchema: boolean;
+  hasOrganizationSchema: boolean;
+  detectedPhones: string[];
+  detectedAddresses: string[];
+  schemaData: {
+    name?: string;
+    address?: string;
+    phone?: string;
+    hours?: string[];
+    geo?: { lat: number; lng: number };
+  } | null;
+  socialProfiles: string[];
+}
+
+/**
+ * Extract and validate LocalBusiness/Organization schema
+ */
+function extractSchema(html: string): {
+  hasLocalBusiness: boolean;
+  hasOrganization: boolean;
+  schemaData: LocalSEOData['schemaData'];
+} {
+  const $ = cheerio.load(html);
+  let hasLocalBusiness = false;
+  let hasOrganization = false;
+  let schemaData: LocalSEOData['schemaData'] = null;
+
+  // Find JSON-LD scripts
+  $('script[type="application/ld+json"]').each((_, el) => {
+    try {
+      const content = $(el).html();
+      if (!content) return;
+
+      const jsonData = JSON.parse(content);
+      const schemas = Array.isArray(jsonData) ? jsonData : [jsonData];
+
+      for (const schema of schemas) {
+        // Handle @graph structure
+        const items = schema['@graph'] || [schema];
+
+        for (const item of items) {
+          const type = item['@type'];
+
+          // Check for LocalBusiness and its subtypes
+          const localBusinessTypes = [
+            'LocalBusiness',
+            'Restaurant',
+            'Store',
+            'MedicalBusiness',
+            'FinancialService',
+            'FoodEstablishment',
+            'HealthAndBeautyBusiness',
+            'HomeAndConstructionBusiness',
+            'LegalService',
+            'RealEstateAgent',
+            'SportsActivityLocation',
+          ];
+
+          if (localBusinessTypes.some((t) => type === t || (Array.isArray(type) && type.includes(t)))) {
+            hasLocalBusiness = true;
+            schemaData = {
+              name: item.name,
+              address: formatAddress(item.address),
+              phone: item.telephone,
+              hours: item.openingHours,
+              geo: item.geo ? { lat: item.geo.latitude, lng: item.geo.longitude } : undefined,
+            };
+          }
+
+          if (type === 'Organization' || type === 'Corporation' || type === 'Person') {
+            hasOrganization = true;
+            if (!schemaData) {
+              schemaData = {
+                name: item.name,
+                address: formatAddress(item.address),
+                phone: item.telephone,
+              };
+            }
+          }
+        }
+      }
+    } catch {
+      // Invalid JSON-LD, skip
+    }
+  });
+
+  return { hasLocalBusiness, hasOrganization, schemaData };
+}
+
+/**
+ * Format address from schema
+ */
+function formatAddress(address: unknown): string | undefined {
+  if (!address) return undefined;
+  if (typeof address === 'string') return address;
+  if (typeof address === 'object' && address !== null) {
+    const a = address as Record<string, string>;
+    return [a.streetAddress, a.addressLocality, a.addressRegion, a.postalCode, a.addressCountry].filter(Boolean).join(', ');
+  }
+  return undefined;
+}
+
+/**
+ * Detect phone numbers in page content
+ */
+function detectPhones(html: string): string[] {
+  const $ = cheerio.load(html);
+  const text = $('body').text();
+  const phones = new Set<string>();
+
+  // Find tel: links
+  $('a[href^="tel:"]').each((_, el) => {
+    const href = $(el).attr('href');
+    if (href) {
+      phones.add(href.replace('tel:', '').trim());
+    }
+  });
+
+  // Find phone patterns in text
+  for (const pattern of PHONE_PATTERNS) {
+    const matches = text.match(pattern);
+    if (matches) {
+      matches.forEach((m) => phones.add(m.trim()));
+    }
+  }
+
+  // Filter out obviously invalid numbers
+  return Array.from(phones).filter((phone) => {
+    const digits = phone.replace(/\D/g, '');
+    return digits.length >= 10 && digits.length <= 15;
+  });
+}
+
+/**
+ * Detect addresses in page content
+ */
+function detectAddresses(html: string): string[] {
+  const $ = cheerio.load(html);
+  const text = $('body').text();
+  const addresses = new Set<string>();
+
+  // Find address patterns
+  for (const pattern of ADDRESS_PATTERNS) {
+    const matches = text.match(pattern);
+    if (matches) {
+      matches.forEach((m) => addresses.add(m.trim()));
+    }
+  }
+
+  // Check for schema addresses
+  $('[itemprop="address"]').each((_, el) => {
+    const addr = $(el).text().trim();
+    if (addr) addresses.add(addr);
+  });
+
+  return Array.from(addresses);
+}
+
+/**
+ * Detect linked social profiles
+ */
+function detectSocialProfiles(html: string): string[] {
+  const $ = cheerio.load(html);
+  const profiles: string[] = [];
+
+  const socialDomains = [
+    'facebook.com',
+    'twitter.com',
+    'x.com',
+    'linkedin.com',
+    'instagram.com',
+    'youtube.com',
+    'tiktok.com',
+    'pinterest.com',
+    'github.com',
+  ];
+
+  $('a[href]').each((_, el) => {
+    const href = $(el).attr('href');
+    if (!href) return;
+
+    for (const domain of socialDomains) {
+      if (href.includes(domain)) {
+        // Normalize the URL
+        try {
+          const url = new URL(href);
+          if (!profiles.includes(url.href)) {
+            profiles.push(url.href);
+          }
+        } catch {
+          // Invalid URL, skip
+        }
+        break;
+      }
+    }
+  });
+
+  return profiles;
+}
+
+/**
+ * Analyze local SEO elements
+ */
+export function analyzeLocalSEO(html: string, url: string): { issues: AuditIssue[]; data: LocalSEOData } {
+  const issues: AuditIssue[] = [];
+
+  // Extract schema
+  const { hasLocalBusiness, hasOrganization, schemaData } = extractSchema(html);
+
+  // Detect phones and addresses
+  const detectedPhones = detectPhones(html);
+  const detectedAddresses = detectAddresses(html);
+
+  // Detect social profiles
+  const socialProfiles = detectSocialProfiles(html);
+
+  // Generate issues
+  if (!hasLocalBusiness) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.LOCAL_BUSINESS_SCHEMA_MISSING,
+      affectedUrls: [url],
+    });
+  }
+
+  if (!hasOrganization && !hasLocalBusiness) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.ORGANIZATION_SCHEMA_MISSING,
+      affectedUrls: [url],
+    });
+  }
+
+  // Only flag missing address/phone for pages that appear to be business pages
+  const $ = cheerio.load(html);
+  const isBusinessPage =
+    $('a[href^="tel:"]').length > 0 ||
+    $('a[href^="mailto:"]').length > 0 ||
+    html.toLowerCase().includes('contact') ||
+    html.toLowerCase().includes('about us');
+
+  if (isBusinessPage) {
+    if (detectedAddresses.length === 0 && !schemaData?.address) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.ADDRESS_NOT_DETECTED,
+        affectedUrls: [url],
+      });
+    }
+
+    if (detectedPhones.length === 0 && !schemaData?.phone) {
+      issues.push({
+        ...ISSUE_DEFINITIONS.PHONE_NOT_DETECTED,
+        affectedUrls: [url],
+      });
+    }
+  }
+
+  // Check for social profiles
+  if (socialProfiles.length === 0) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.SOCIAL_PROFILES_NOT_LINKED,
+      affectedUrls: [url],
+    });
+  }
+
+  return {
+    issues,
+    data: {
+      hasLocalBusinessSchema: hasLocalBusiness,
+      hasOrganizationSchema: hasOrganization,
+      detectedPhones,
+      detectedAddresses,
+      schemaData,
+      socialProfiles,
+    },
+  };
+}

package/src/audit/checks/mobile.ts

@@ -0,0 +1,167 @@
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../types.js';
+import { ISSUE_DEFINITIONS } from '../types.js';
+
+export interface MobileData {
+  hasViewport: boolean;
+  viewportContent?: string;
+  isResponsive: boolean;
+  tapTargetIssues: number;
+  fontSizeIssues: number;
+}
+
+export function analyzeMobile(html: string, url: string): { issues: AuditIssue[]; data: MobileData } {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+
+  // Check viewport meta tag
+  const viewportMeta = $('meta[name="viewport"]');
+  const hasViewport = viewportMeta.length > 0;
+  const viewportContent = viewportMeta.attr('content');
+
+  if (!hasViewport) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.VIEWPORT_MISSING,
+      affectedUrls: [url],
+    });
+  } else if (viewportContent) {
+    // Check if viewport is responsive
+    const isResponsive = viewportContent.includes('width=device-width');
+
+    if (!isResponsive) {
+      // Check for fixed width
+      const widthMatch = viewportContent.match(/width=(\d+)/);
+      if (widthMatch) {
+        issues.push({
+          ...ISSUE_DEFINITIONS.VIEWPORT_NOT_RESPONSIVE,
+          affectedUrls: [url],
+          details: {
+            viewport: viewportContent,
+            fixedWidth: widthMatch[1],
+          },
+        });
+      }
+    }
+
+    // Check for user-scalable=no (bad for accessibility)
+    if (viewportContent.includes('user-scalable=no') || viewportContent.includes('user-scalable=0')) {
+      issues.push({
+        code: 'VIEWPORT_NO_ZOOM',
+        severity: 'warning',
+        category: 'mobile',
+        title: 'Viewport prevents zooming',
+        description: 'The viewport meta tag disables user scaling.',
+        impact: 'Users with visual impairments cannot zoom the page.',
+        howToFix: 'Remove user-scalable=no from the viewport meta tag.',
+        affectedUrls: [url],
+      });
+    }
+  }
+
+  // Check for tap target issues (basic heuristic)
+  // In a real implementation, this would analyze CSS computed styles
+  let tapTargetIssues = 0;
+  $('a, button, input, select, textarea').each((_, el) => {
+    const style = $(el).attr('style') || '';
+    // Basic check for very small explicit sizes
+    const heightMatch = style.match(/height:\s*(\d+)px/);
+    const widthMatch = style.match(/width:\s*(\d+)px/);
+
+    if (heightMatch && parseInt(heightMatch[1], 10) < 44) {
+      tapTargetIssues++;
+    }
+    if (widthMatch && parseInt(widthMatch[1], 10) < 44) {
+      tapTargetIssues++;
+    }
+  });
+
+  if (tapTargetIssues > 0) {
+    issues.push({
+      ...ISSUE_DEFINITIONS.TAP_TARGETS_TOO_SMALL,
+      affectedUrls: [url],
+      details: { count: tapTargetIssues },
+    });
+  }
+
+  // Check for font size issues (basic heuristic)
+  let fontSizeIssues = 0;
+  $('body *').each((_, el) => {
+    const style = $(el).attr('style') || '';
+    const fontSizeMatch = style.match(/font-size:\s*(\d+)px/);
+    if (fontSizeMatch && parseInt(fontSizeMatch[1], 10) < 12) {
+      fontSizeIssues++;
+    }
+  });
+
+  return {
+    issues,
+    data: {
+      hasViewport,
+      viewportContent,
+      isResponsive: hasViewport && (viewportContent?.includes('width=device-width') || false),
+      tapTargetIssues,
+      fontSizeIssues,
+    }
+  };
+}
+
+// Additional mobile-specific checks
+export function checkMobileResources(html: string, url: string): AuditIssue[] {
+  const issues: AuditIssue[] = [];
+  const $ = cheerio.load(html);
+
+  // Check for Flash content (obsolete)
+  if ($('object[type*="flash"], embed[type*="flash"]').length > 0) {
+    issues.push({
+      code: 'FLASH_CONTENT',
+      severity: 'error',
+      category: 'mobile',
+      title: 'Flash content detected',
+      description: 'Page contains Flash content which is not supported on mobile devices.',
+      impact: 'Content is inaccessible on mobile devices and most modern browsers.',
+      howToFix: 'Replace Flash content with HTML5 alternatives.',
+      affectedUrls: [url],
+    });
+  }
+
+  // Check for plugins
+  if ($('object, embed, applet').length > 0) {
+    issues.push({
+      code: 'PLUGINS_DETECTED',
+      severity: 'notice',
+      category: 'mobile',
+      title: 'Plugins detected',
+      description: 'Page uses plugins which may not work on mobile devices.',
+      impact: 'Some content may not be accessible on mobile.',
+      howToFix: 'Consider replacing plugins with standard web technologies.',
+      affectedUrls: [url],
+    });
+  }
+
+  // Check for horizontal scroll (indication of non-responsive design)
+  // This is a heuristic based on fixed-width elements
+  let fixedWidthElements = 0;
+  $('*').each((_, el) => {
+    const style = $(el).attr('style') || '';
+    const widthMatch = style.match(/width:\s*(\d+)px/);
+    if (widthMatch && parseInt(widthMatch[1], 10) > 320) {
+      fixedWidthElements++;
+    }
+  });
+
+  if (fixedWidthElements > 5) {
+    issues.push({
+      code: 'POSSIBLE_HORIZONTAL_SCROLL',
+      severity: 'notice',
+      category: 'mobile',
+      title: 'Possible horizontal scrolling',
+      description: 'Multiple elements have fixed widths that may cause horizontal scrolling on mobile.',
+      impact: 'Poor mobile user experience.',
+      howToFix: 'Use responsive widths (percentages, max-width) instead of fixed pixel widths.',
+      affectedUrls: [url],
+      details: { count: fixedWidthElements },
+    });
+  }
+
+  return issues;
+}