@rankcli/agent-runtime 0.0.8 → 0.0.11

package/src/analyzers/structured-data-analyzer.ts

@@ -0,0 +1,590 @@
+/**
+ * Structured Data / Schema.org Analyzer
+ * 
+ * Validates JSON-LD structured data for SEO and AI search optimization.
+ * Checks for common schema types, required properties, and best practices.
+ */
+
+import * as cheerio from 'cheerio';
+import type { AuditIssue } from '../audit/types.js';
+
+export interface StructuredDataResult {
+  score: number;
+  schemas: SchemaItem[];
+  hasOrganization: boolean;
+  hasWebSite: boolean;
+  hasWebPage: boolean;
+  hasBreadcrumb: boolean;
+  hasArticle: boolean;
+  hasProduct: boolean;
+  hasFAQ: boolean;
+  hasHowTo: boolean;
+  hasLocalBusiness: boolean;
+  hasEvent: boolean;
+  hasReview: boolean;
+  issues: AuditIssue[];
+  recommendations: string[];
+}
+
+export interface SchemaItem {
+  type: string;
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+  properties: string[];
+}
+
+// Required and recommended properties for common schema types
+const SCHEMA_REQUIREMENTS: Record<string, { required: string[]; recommended: string[] }> = {
+  'Organization': {
+    required: ['name', 'url'],
+    recommended: ['logo', 'sameAs', 'contactPoint', 'address'],
+  },
+  'WebSite': {
+    required: ['name', 'url'],
+    recommended: ['potentialAction', 'publisher'],
+  },
+  'WebPage': {
+    required: ['name'],
+    recommended: ['description', 'url', 'breadcrumb', 'mainEntity'],
+  },
+  'Article': {
+    required: ['headline', 'author', 'datePublished'],
+    recommended: ['image', 'dateModified', 'publisher', 'description', 'mainEntityOfPage'],
+  },
+  'BlogPosting': {
+    required: ['headline', 'author', 'datePublished'],
+    recommended: ['image', 'dateModified', 'publisher', 'description'],
+  },
+  'NewsArticle': {
+    required: ['headline', 'author', 'datePublished', 'image'],
+    recommended: ['dateModified', 'publisher', 'description'],
+  },
+  'Product': {
+    required: ['name'],
+    recommended: ['image', 'description', 'offers', 'brand', 'sku', 'aggregateRating', 'review'],
+  },
+  'Offer': {
+    required: ['price', 'priceCurrency'],
+    recommended: ['availability', 'url', 'priceValidUntil'],
+  },
+  'FAQPage': {
+    required: ['mainEntity'],
+    recommended: [],
+  },
+  'Question': {
+    required: ['name', 'acceptedAnswer'],
+    recommended: [],
+  },
+  'HowTo': {
+    required: ['name', 'step'],
+    recommended: ['image', 'totalTime', 'estimatedCost', 'supply', 'tool'],
+  },
+  'BreadcrumbList': {
+    required: ['itemListElement'],
+    recommended: [],
+  },
+  'LocalBusiness': {
+    required: ['name', 'address'],
+    recommended: ['telephone', 'openingHours', 'geo', 'image', 'priceRange'],
+  },
+  'Event': {
+    required: ['name', 'startDate', 'location'],
+    recommended: ['endDate', 'description', 'image', 'offers', 'performer', 'organizer'],
+  },
+  'Review': {
+    required: ['itemReviewed', 'reviewRating', 'author'],
+    recommended: ['reviewBody', 'datePublished'],
+  },
+  'AggregateRating': {
+    required: ['ratingValue', 'reviewCount'],
+    recommended: ['bestRating', 'worstRating'],
+  },
+  'Person': {
+    required: ['name'],
+    recommended: ['url', 'image', 'jobTitle', 'sameAs'],
+  },
+  'VideoObject': {
+    required: ['name', 'thumbnailUrl', 'uploadDate'],
+    recommended: ['description', 'contentUrl', 'duration', 'embedUrl'],
+  },
+  'ImageObject': {
+    required: ['contentUrl'],
+    recommended: ['caption', 'creditText', 'creator'],
+  },
+  'SoftwareApplication': {
+    required: ['name'],
+    recommended: ['operatingSystem', 'applicationCategory', 'offers', 'aggregateRating'],
+  },
+  'Recipe': {
+    required: ['name', 'recipeIngredient', 'recipeInstructions'],
+    recommended: ['image', 'author', 'prepTime', 'cookTime', 'totalTime', 'nutrition'],
+  },
+  'Course': {
+    required: ['name', 'provider'],
+    recommended: ['description', 'offers'],
+  },
+};
+
+/**
+ * Parse and validate JSON-LD structured data
+ */
+function parseJsonLd(script: string): { data: any; error?: string } {
+  try {
+    const data = JSON.parse(script);
+    return { data };
+  } catch (e) {
+    return { data: null, error: `Invalid JSON: ${(e as Error).message}` };
+  }
+}
+
+/**
+ * Get all types from a schema object (handles @graph and nested types)
+ */
+function extractTypes(data: any): string[] {
+  const types: string[] = [];
+  
+  if (!data) return types;
+  
+  if (Array.isArray(data)) {
+    for (const item of data) {
+      types.push(...extractTypes(item));
+    }
+  } else if (typeof data === 'object') {
+    if (data['@type']) {
+      const schemaType = Array.isArray(data['@type']) ? data['@type'] : [data['@type']];
+      types.push(...schemaType);
+    }
+    if (data['@graph']) {
+      types.push(...extractTypes(data['@graph']));
+    }
+  }
+  
+  return types;
+}
+
+/**
+ * Validate a schema object against requirements
+ */
+function validateSchema(data: any, type: string): SchemaItem {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const properties: string[] = [];
+  
+  if (!data || typeof data !== 'object') {
+    return { type, isValid: false, errors: ['Invalid schema object'], warnings, properties };
+  }
+  
+  // Extract properties
+  for (const key of Object.keys(data)) {
+    if (!key.startsWith('@')) {
+      properties.push(key);
+    }
+  }
+  
+  // Check requirements
+  const requirements = SCHEMA_REQUIREMENTS[type];
+  if (requirements) {
+    // Check required properties
+    for (const prop of requirements.required) {
+      if (!data[prop]) {
+        errors.push(`Missing required property: ${prop}`);
+      }
+    }
+    
+    // Check recommended properties
+    for (const prop of requirements.recommended) {
+      if (!data[prop]) {
+        warnings.push(`Missing recommended property: ${prop}`);
+      }
+    }
+  }
+  
+  // Type-specific validations
+  if (type === 'Article' || type === 'BlogPosting' || type === 'NewsArticle') {
+    // Check for proper author format
+    if (data.author && typeof data.author === 'string') {
+      warnings.push('author should be a Person or Organization object, not a string');
+    }
+    // Check for proper publisher format
+    if (data.publisher && typeof data.publisher === 'string') {
+      warnings.push('publisher should be an Organization object, not a string');
+    }
+    // Check date format
+    if (data.datePublished && !/^\d{4}-\d{2}-\d{2}/.test(data.datePublished)) {
+      warnings.push('datePublished should be in ISO 8601 format (YYYY-MM-DD)');
+    }
+  }
+  
+  if (type === 'Product') {
+    // Check for offers
+    if (!data.offers) {
+      warnings.push('Product without offers/price - may not show rich results');
+    }
+  }
+  
+  if (type === 'FAQPage') {
+    // Check for valid Q&A structure
+    if (data.mainEntity) {
+      const questions = Array.isArray(data.mainEntity) ? data.mainEntity : [data.mainEntity];
+      for (let i = 0; i < questions.length; i++) {
+        const q = questions[i];
+        if (!q.name && !q['@type']?.includes('Question')) {
+          errors.push(`FAQ item ${i + 1} is not a valid Question`);
+        }
+        if (!q.acceptedAnswer) {
+          errors.push(`FAQ item ${i + 1} missing acceptedAnswer`);
+        }
+      }
+    }
+  }
+  
+  if (type === 'BreadcrumbList') {
+    // Check for proper item list
+    if (data.itemListElement) {
+      const items = Array.isArray(data.itemListElement) ? data.itemListElement : [data.itemListElement];
+      items.forEach((item: Record<string, unknown>, i: number) => {
+        if (!item.position) {
+          errors.push(`Breadcrumb item ${i + 1} missing position`);
+        }
+        if (!item.name && !(item.item as Record<string, unknown>)?.name) {
+          errors.push(`Breadcrumb item ${i + 1} missing name`);
+        }
+      });
+    }
+  }
+  
+  if (type === 'LocalBusiness') {
+    // Check for geo coordinates
+    if (data.geo) {
+      if (!data.geo.latitude || !data.geo.longitude) {
+        warnings.push('geo should include latitude and longitude');
+      }
+    }
+    // Check opening hours format
+    if (data.openingHours && typeof data.openingHours === 'string') {
+      warnings.push('openingHours should be an array of OpeningHoursSpecification objects for rich results');
+    }
+  }
+  
+  return {
+    type,
+    isValid: errors.length === 0,
+    errors,
+    warnings,
+    properties,
+  };
+}
+
+/**
+ * Analyze all structured data on a page
+ */
+export function analyzeStructuredData(html: string, url: string): StructuredDataResult {
+  const $ = cheerio.load(html);
+  const schemas: SchemaItem[] = [];
+  const issues: AuditIssue[] = [];
+  const recommendations: string[] = [];
+  let score = 100;
+  
+  // Track schema types
+  const foundTypes = new Set<string>();
+  
+  // Parse all JSON-LD scripts
+  $('script[type="application/ld+json"]').each((_, el) => {
+    const content = $(el).html();
+    if (!content) return;
+    
+    const { data, error } = parseJsonLd(content);
+    
+    if (error) {
+      issues.push({
+        code: 'SCHEMA_INVALID_JSON',
+        severity: 'critical',
+        category: 'technical',
+        title: 'Invalid JSON-LD syntax',
+        description: error,
+        impact: 'Schema will not be parsed by search engines',
+        howToFix: 'Fix JSON syntax errors. Use a JSON validator.',
+        affectedUrls: [url],
+      });
+      score -= 20;
+      return;
+    }
+    
+    // Extract and validate all types
+    const types = extractTypes(data);
+    
+    // Process each schema item
+    const processItem = (item: any) => {
+      if (!item || typeof item !== 'object') return;
+      
+      let itemType = item['@type'];
+      if (Array.isArray(itemType)) itemType = itemType[0];
+      
+      if (itemType) {
+        foundTypes.add(itemType);
+        const validation = validateSchema(item, itemType);
+        schemas.push(validation);
+        
+        if (!validation.isValid) {
+          for (const err of validation.errors) {
+            issues.push({
+              code: 'SCHEMA_VALIDATION_ERROR',
+              severity: 'warning',
+              category: 'technical',
+              title: `${itemType} schema error: ${err}`,
+              description: `The ${itemType} schema is missing required properties or has invalid data.`,
+              impact: 'May not qualify for rich results',
+              howToFix: `Add the missing property: ${err.replace('Missing required property: ', '')}`,
+              affectedUrls: [url],
+            });
+            score -= 5;
+          }
+        }
+      }
+      
+      // Process @graph
+      if (item['@graph'] && Array.isArray(item['@graph'])) {
+        item['@graph'].forEach(processItem);
+      }
+    };
+    
+    if (Array.isArray(data)) {
+      data.forEach(processItem);
+    } else {
+      processItem(data);
+    }
+  });
+  
+  // Check for essential schemas
+  const hasOrganization = foundTypes.has('Organization');
+  const hasWebSite = foundTypes.has('WebSite');
+  const hasWebPage = foundTypes.has('WebPage');
+  const hasBreadcrumb = foundTypes.has('BreadcrumbList');
+  const hasArticle = foundTypes.has('Article') || foundTypes.has('BlogPosting') || foundTypes.has('NewsArticle');
+  const hasProduct = foundTypes.has('Product');
+  const hasFAQ = foundTypes.has('FAQPage');
+  const hasHowTo = foundTypes.has('HowTo');
+  const hasLocalBusiness = foundTypes.has('LocalBusiness');
+  const hasEvent = foundTypes.has('Event');
+  const hasReview = foundTypes.has('Review') || foundTypes.has('AggregateRating');
+  
+  // Generate recommendations
+  if (!hasOrganization) {
+    recommendations.push('Add Organization schema for brand knowledge panel');
+    score -= 5;
+  }
+  
+  if (!hasWebSite) {
+    recommendations.push('Add WebSite schema with SearchAction for sitelinks search box');
+    score -= 3;
+  }
+  
+  if (!hasBreadcrumb) {
+    recommendations.push('Add BreadcrumbList schema for breadcrumb rich results');
+    score -= 3;
+  }
+  
+  // Check for page-type specific schemas
+  if (!hasArticle && !hasProduct && !hasFAQ && !hasHowTo && !hasLocalBusiness && !hasEvent) {
+    recommendations.push('Add page-specific schema (Article, Product, FAQ, HowTo, etc.)');
+    score -= 10;
+    
+    issues.push({
+      code: 'SCHEMA_NO_RICH_RESULT_TYPE',
+      severity: 'warning',
+      category: 'technical',
+      title: 'No rich result schema found',
+      description: 'Page lacks schema types that enable rich results (Article, Product, FAQ, etc.)',
+      impact: 'Missing opportunity for enhanced search results',
+      howToFix: 'Add appropriate schema type for your content (e.g., Article for blog posts, Product for products, FAQ for Q&A)',
+      affectedUrls: [url],
+    });
+  }
+  
+  // Check for no schema at all
+  if (schemas.length === 0) {
+    score -= 20;
+    issues.push({
+      code: 'SCHEMA_NONE_FOUND',
+      severity: 'warning',
+      category: 'technical',
+      title: 'No structured data found',
+      description: 'No JSON-LD structured data detected on the page.',
+      impact: 'Missing rich results, reduced AI understanding, lower search visibility',
+      howToFix: 'Add JSON-LD structured data. At minimum, include Organization and WebPage schemas.',
+      affectedUrls: [url],
+    });
+  }
+  
+  // AI-specific recommendations
+  if (schemas.length > 0 && !hasFAQ) {
+    recommendations.push('Consider adding FAQPage schema - excellent for AI search citations');
+  }
+  
+  if (!foundTypes.has('Person') && hasArticle) {
+    recommendations.push('Use Person schema for authors to improve E-E-A-T signals');
+  }
+  
+  return {
+    score: Math.max(0, Math.min(100, score)),
+    schemas,
+    hasOrganization,
+    hasWebSite,
+    hasWebPage,
+    hasBreadcrumb,
+    hasArticle,
+    hasProduct,
+    hasFAQ,
+    hasHowTo,
+    hasLocalBusiness,
+    hasEvent,
+    hasReview,
+    issues,
+    recommendations,
+  };
+}
+
+/**
+ * Generate recommended schema for a page type
+ */
+export function generateSchemaTemplate(pageType: 'article' | 'product' | 'faq' | 'local-business' | 'website', options: {
+  siteName: string;
+  siteUrl: string;
+  authorName?: string;
+  organizationName?: string;
+}): string {
+  const { siteName, siteUrl, authorName, organizationName } = options;
+  
+  const baseSchemas = [
+    {
+      '@context': 'https://schema.org',
+      '@type': 'Organization',
+      name: organizationName || siteName,
+      url: siteUrl,
+      logo: `${siteUrl}/logo.png`,
+    },
+    {
+      '@context': 'https://schema.org',
+      '@type': 'WebSite',
+      name: siteName,
+      url: siteUrl,
+      potentialAction: {
+        '@type': 'SearchAction',
+        target: {
+          '@type': 'EntryPoint',
+          urlTemplate: `${siteUrl}/search?q={search_term_string}`,
+        },
+        'query-input': 'required name=search_term_string',
+      },
+    },
+  ];
+  
+  const pageSchemas: Record<string, object> = {
+    article: {
+      '@context': 'https://schema.org',
+      '@type': 'Article',
+      headline: '{{title}}',
+      description: '{{description}}',
+      image: '{{image_url}}',
+      datePublished: '{{date_published}}',
+      dateModified: '{{date_modified}}',
+      author: {
+        '@type': 'Person',
+        name: authorName || '{{author_name}}',
+        url: '{{author_url}}',
+      },
+      publisher: {
+        '@type': 'Organization',
+        name: organizationName || siteName,
+        logo: {
+          '@type': 'ImageObject',
+          url: `${siteUrl}/logo.png`,
+        },
+      },
+    },
+    product: {
+      '@context': 'https://schema.org',
+      '@type': 'Product',
+      name: '{{product_name}}',
+      description: '{{product_description}}',
+      image: '{{product_image}}',
+      brand: {
+        '@type': 'Brand',
+        name: '{{brand_name}}',
+      },
+      sku: '{{sku}}',
+      offers: {
+        '@type': 'Offer',
+        price: '{{price}}',
+        priceCurrency: 'USD',
+        availability: 'https://schema.org/InStock',
+        url: '{{product_url}}',
+      },
+      aggregateRating: {
+        '@type': 'AggregateRating',
+        ratingValue: '{{rating}}',
+        reviewCount: '{{review_count}}',
+      },
+    },
+    faq: {
+      '@context': 'https://schema.org',
+      '@type': 'FAQPage',
+      mainEntity: [
+        {
+          '@type': 'Question',
+          name: '{{question_1}}',
+          acceptedAnswer: {
+            '@type': 'Answer',
+            text: '{{answer_1}}',
+          },
+        },
+        {
+          '@type': 'Question',
+          name: '{{question_2}}',
+          acceptedAnswer: {
+            '@type': 'Answer',
+            text: '{{answer_2}}',
+          },
+        },
+      ],
+    },
+    'local-business': {
+      '@context': 'https://schema.org',
+      '@type': 'LocalBusiness',
+      name: '{{business_name}}',
+      description: '{{description}}',
+      url: siteUrl,
+      telephone: '{{phone}}',
+      address: {
+        '@type': 'PostalAddress',
+        streetAddress: '{{street}}',
+        addressLocality: '{{city}}',
+        addressRegion: '{{state}}',
+        postalCode: '{{zip}}',
+        addressCountry: '{{country}}',
+      },
+      geo: {
+        '@type': 'GeoCoordinates',
+        latitude: '{{latitude}}',
+        longitude: '{{longitude}}',
+      },
+      openingHoursSpecification: [
+        {
+          '@type': 'OpeningHoursSpecification',
+          dayOfWeek: ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'],
+          opens: '09:00',
+          closes: '17:00',
+        },
+      ],
+    },
+    website: baseSchemas[1],
+  };
+  
+  const result: object[] = [...baseSchemas];
+  if (pageType !== 'website' && pageSchemas[pageType]) {
+    result.push(pageSchemas[pageType]);
+  }
+  
+  return JSON.stringify(result, null, 2);
+}

package/src/audit/engine.ts

@@ -454,7 +454,7 @@ function createReport(url: string, domain: string, issues: AuditIssue[], pages:
 
 function calculateHealthScore(issues: AuditIssue[]): HealthScore {
   // Weight issues by severity
-  const weights = { error: 10, warning: 3, notice: 1 };
+  const weights: Record<string, number> = { critical: 15, error: 10, warning: 3, info: 1, notice: 1 };
 
   // Calculate deductions per category
   const categoryDeductions: Record<string, number> = {
@@ -611,8 +611,8 @@ function groupIssuesByCategory(issues: AuditIssue[]): Record<string, AuditIssue[
   // Sort by severity within each category
   for (const category of Object.keys(grouped)) {
     grouped[category].sort((a, b) => {
-      const order = { error: 0, warning: 1, notice: 2 };
-      return order[a.severity] - order[b.severity];
+      const order: Record<string, number> = { critical: 0, error: 1, warning: 2, info: 3, notice: 4 };
+      return (order[a.severity] ?? 5) - (order[b.severity] ?? 5);
     });
   }
 

package/src/audit/types.ts

@@ -1,6 +1,6 @@
 // Comprehensive SEO Audit Types - Matching Ahrefs 170+ checks
 
-export type IssueSeverity = 'error' | 'warning' | 'notice';
+export type IssueSeverity = 'critical' | 'error' | 'warning' | 'info' | 'notice';
 
 export type IssueCategory =
   | 'crawlability'
@@ -18,7 +18,8 @@ export type IssueCategory =
   | 'social'
   | 'local-seo'
   | 'accessibility'
-  | 'framework';
+  | 'framework'
+  | 'technical';
 
 export interface AuditIssue {
   code: string;