@rankcli/agent-runtime 0.0.14 → 0.0.16

package/src/frameworks/recipes/wordpress.yaml

@@ -1,209 +0,0 @@
-# WordPress SEO Recipe
-# WordPress powers 40%+ of the web - SEO is well-supported with plugins
-
-framework: wordpress
-display_name: WordPress
-category: cms
-ssr_default: true  # PHP renders on server
-
-seo_strengths:
-  - "Server-rendered HTML by default"
-  - "Mature SEO plugin ecosystem"
-  - "Built-in canonical URL support"
-  - "Sitemap generation via plugins"
-  - "Structured data plugins available"
-
-seo_challenges:
-  - "Plugin bloat can slow performance"
-  - "Default themes often lack optimization"
-  - "Image optimization requires plugins"
-  - "Caching needed for performance"
-
-checks:
-  - code: WORDPRESS_NO_SEO_PLUGIN
-    severity: warning
-    title: "No SEO plugin detected"
-    description: "WordPress benefits greatly from an SEO plugin like Yoast or Rank Math."
-    howToFix: |
-      Install an SEO plugin:
-
-      **Yoast SEO** (most popular):
-      1. Go to Plugins > Add New
-      2. Search "Yoast SEO"
-      3. Install and activate
-
-      **Rank Math** (feature-rich free tier):
-      1. Go to Plugins > Add New
-      2. Search "Rank Math"
-      3. Install and activate
-
-      Both provide:
-      - Meta title/description management
-      - XML sitemap generation
-      - Schema markup
-      - Content analysis
-
-  - code: WORDPRESS_OUTDATED
-    severity: error
-    title: "WordPress core is outdated"
-    description: "Running outdated WordPress is a security risk and may have SEO bugs."
-    howToFix: |
-      Update WordPress:
-      1. Backup your site first
-      2. Go to Dashboard > Updates
-      3. Click "Update Now"
-
-      Enable auto-updates in wp-config.php:
-      ```php
-      define('WP_AUTO_UPDATE_CORE', true);
-      ```
-
-  - code: WORDPRESS_NO_CACHING
-    severity: warning
-    title: "No caching plugin detected"
-    description: "WordPress without caching is slow, hurting Core Web Vitals."
-    howToFix: |
-      Install a caching plugin:
-
-      **WP Super Cache** (simple):
-      - Easy setup, good for most sites
-
-      **W3 Total Cache** (advanced):
-      - More features, steeper learning curve
-
-      **LiteSpeed Cache** (if on LiteSpeed server):
-      - Best performance on compatible hosts
-
-  - code: WORDPRESS_LARGE_IMAGES
-    severity: warning
-    title: "Images not optimized"
-    description: "Large images slow down WordPress significantly."
-    howToFix: |
-      Install an image optimization plugin:
-
-      **ShortPixel** or **Smush**:
-      - Compresses existing images
-      - Optimizes on upload
-      - WebP conversion
-
-      Or use Cloudflare Polish for automatic optimization.
-
-  - code: WORDPRESS_TOO_MANY_PLUGINS
-    severity: warning
-    title: "Too many plugins installed"
-    description: "Each plugin adds overhead. Many sites have 30+ plugins when 10-15 suffice."
-    howToFix: |
-      Audit your plugins:
-      1. Go to Plugins > Installed Plugins
-      2. Deactivate plugins not in use
-      3. Delete deactivated plugins
-      4. Consider consolidating (one SEO plugin, one security plugin)
-
-      Aim for under 20 plugins.
-
-  - code: WORDPRESS_NO_LAZY_LOAD
-    severity: notice
-    title: "Native lazy loading not enabled"
-    description: "WordPress 5.5+ has native lazy loading, but themes may disable it."
-    howToFix: |
-      Check if lazy loading is enabled:
-      ```php
-      // In functions.php, remove if present:
-      add_filter('wp_lazy_loading_enabled', '__return_false');
-      ```
-
-      For older WordPress, add:
-      ```php
-      add_filter('wp_lazy_loading_enabled', '__return_true');
-      ```
-
-  - code: WORDPRESS_NO_WEBP
-    severity: notice
-    title: "Not serving WebP images"
-    description: "WebP images are 25-35% smaller than JPEG."
-    howToFix: |
-      Use a plugin that serves WebP:
-
-      1. **ShortPixel**: Auto-converts and serves WebP
-      2. **WebP Express**: Converts and configures server
-
-      Or use Cloudflare with Polish enabled for automatic WebP.
-
-  - code: WORDPRESS_NO_PRELOAD_HINTS
-    severity: notice
-    title: "Missing resource hints"
-    description: "Preload hints can speed up critical resources."
-    howToFix: |
-      Add to your theme's functions.php:
-
-      ```php
-      function add_resource_hints() {
-        // Preload critical font
-        echo '<link rel="preload" href="/wp-content/themes/yourtheme/fonts/main.woff2" as="font" type="font/woff2" crossorigin>';
-
-        // Preconnect to external domains
-        echo '<link rel="preconnect" href="https://fonts.googleapis.com">';
-      }
-      add_action('wp_head', 'add_resource_hints', 1);
-      ```
-
-  - code: WORDPRESS_BLOCKING_SCRIPTS
-    severity: warning
-    title: "Render-blocking scripts detected"
-    description: "JavaScript in <head> blocks rendering."
-    howToFix: |
-      Use a plugin like **Autoptimize** or **Asset CleanUp** to:
-      - Defer JavaScript
-      - Inline critical CSS
-      - Combine files
-
-      Or add defer manually in functions.php:
-      ```php
-      function defer_scripts($tag, $handle) {
-        if (is_admin()) return $tag;
-        return str_replace(' src', ' defer src', $tag);
-      }
-      add_filter('script_loader_tag', 'defer_scripts', 10, 2);
-      ```
-
-  - code: WORDPRESS_NO_SCHEMA
-    severity: warning
-    title: "No structured data detected"
-    description: "Schema markup helps with rich snippets."
-    howToFix: |
-      **If using Yoast/Rank Math**: Schema is included.
-
-      **Manual schema** in theme:
-      ```php
-      function add_organization_schema() {
-        if (is_front_page()) {
-          echo '<script type="application/ld+json">
-          {
-            "@context": "https://schema.org",
-            "@type": "Organization",
-            "name": "Your Company",
-            "url": "' . home_url() . '"
-          }
-          </script>';
-        }
-      }
-      add_action('wp_footer', 'add_organization_schema');
-      ```
-
-performance_tips:
-  - "Use a quality managed WordPress host (WP Engine, Kinsta)"
-  - "Enable object caching (Redis/Memcached)"
-  - "Use a CDN (Cloudflare, Fastly)"
-  - "Keep plugins under 20"
-  - "Choose a lightweight theme (GeneratePress, Astra)"
-  - "Disable unnecessary features (emojis, embeds)"
-
-recommended_plugins:
-  seo:
-    - "Yoast SEO or Rank Math"
-  performance:
-    - "WP Super Cache or LiteSpeed Cache"
-    - "ShortPixel or Smush (images)"
-    - "Autoptimize (JS/CSS)"
-  security:
-    - "Wordfence or Sucuri"

package/src/frameworks/suggestion-engine.ts

@@ -1,357 +0,0 @@
-/**
- * Framework-Specific SEO Suggestion Engine
- *
- * Loads recipe files and provides framework-specific SEO suggestions.
- * Works with both CLI and Web UI.
- */
-
-import { parse as parseYaml } from 'yaml';
-import type { Framework, FrameworkInfo } from './detector.js';
-import type { AuditIssue, IssueCategory, IssueSeverity } from '../audit/types.js';
-
-export interface FrameworkCheck {
-  code: string;
-  severity: IssueSeverity;
-  title: string;
-  description: string;
-  howToFix: string;
-  impact?: string;
-  detection?: {
-    html_patterns?: string[];
-    missing_content?: boolean;
-    title_in_js?: boolean;
-    title_not_in_html?: boolean;
-  };
-  app_router_only?: boolean;
-  pages_router_only?: boolean;
-}
-
-export interface FrameworkRecipe {
-  framework: Framework;
-  display_name: string;
-  category: string;
-  base_framework?: Framework;
-  ssr_default: boolean;
-  seo_challenges?: string[];
-  seo_strengths?: string[];
-  checks: FrameworkCheck[];
-  performance_tips?: string[];
-  migration_paths?: Record<string, {
-    effort: string;
-    benefits: string[];
-    guide?: string;
-  }>;
-  recommended_plugins?: Record<string, string[]>;
-  recommended_gems?: Record<string, string[]>;
-  integrations?: string[];
-}
-
-// Embedded recipes (loaded at build time or dynamically)
-const RECIPES: Record<Framework, FrameworkRecipe | null> = {
-  // JavaScript/TypeScript
-  react: null,
-  nextjs: null,
-  vue: null,
-  nuxt: null,
-  angular: null,
-  svelte: null,
-  sveltekit: null,
-  astro: null,
-  remix: null,
-  gatsby: null,
-  solidjs: null,
-  qwik: null,
-  fresh: null,
-  
-  // Ruby
-  rails: null,
-  
-  // Python
-  django: null,
-  flask: null,
-  fastapi: null,
-  
-  // PHP
-  laravel: null,
-  symfony: null,
-  wordpress: null,
-  
-  // Java
-  spring: null,
-  
-  // C#
-  aspnet: null,
-  
-  // Go
-  go: null,
-  
-  // Elixir
-  phoenix: null,
-  
-  // Hypermedia
-  htmx: null,
-  hotwire: null,
-  
-  // Static Site Generators
-  hugo: null,
-  jekyll: null,
-  eleventy: null,
-  pelican: null,
-  
-  // Unknown
-  unknown: null,
-};
-
-// Recipe content will be bundled inline for distribution
-// This allows the suggestion engine to work without file system access
-const RECIPE_CONTENT: Record<string, string> = {};
-
-/**
- * Load a recipe from embedded content or file system
- */
-export async function loadRecipe(framework: Framework): Promise<FrameworkRecipe | null> {
-  if (framework === 'unknown') return null;
-
-  // Check cache
-  if (RECIPES[framework]) {
-    return RECIPES[framework];
-  }
-
-  // Check embedded content
-  if (RECIPE_CONTENT[framework]) {
-    try {
-      const recipe = parseYaml(RECIPE_CONTENT[framework]) as FrameworkRecipe;
-      RECIPES[framework] = recipe;
-      return recipe;
-    } catch {
-      console.warn(`Failed to parse embedded recipe for ${framework}`);
-      return null;
-    }
-  }
-
-  // Try dynamic import for Node.js environment
-  try {
-    const fs = await import('fs');
-    const path = await import('path');
-    const url = await import('url');
-
-    const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
-    const recipePath = path.join(__dirname, 'recipes', `${framework}.yaml`);
-
-    if (fs.existsSync(recipePath)) {
-      const content = fs.readFileSync(recipePath, 'utf-8');
-      const recipe = parseYaml(content) as FrameworkRecipe;
-      RECIPES[framework] = recipe;
-      return recipe;
-    }
-  } catch {
-    // File system not available (browser, edge function)
-  }
-
-  return null;
-}
-
-/**
- * Get framework-specific issues based on HTML analysis
- */
-export async function getFrameworkIssues(
-  frameworkInfo: FrameworkInfo,
-  html: string,
-  url: string
-): Promise<AuditIssue[]> {
-  const recipe = await loadRecipe(frameworkInfo.framework);
-  if (!recipe) return [];
-
-  const issues: AuditIssue[] = [];
-
-  for (const check of recipe.checks) {
-    const matched = evaluateCheck(check, html, frameworkInfo);
-    if (matched) {
-      issues.push({
-        code: check.code,
-        severity: check.severity,
-        category: 'on-page' as IssueCategory, // Framework issues are on-page
-        title: check.title,
-        description: check.description,
-        impact: check.impact || `Framework-specific issue for ${recipe.display_name}`,
-        howToFix: check.howToFix,
-        affectedUrls: [url],
-        details: {
-          framework: recipe.display_name,
-          frameworkCategory: recipe.category,
-        },
-      });
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Evaluate if a check matches the HTML content
- */
-function evaluateCheck(
-  check: FrameworkCheck,
-  html: string,
-  frameworkInfo: FrameworkInfo
-): boolean {
-  // Skip router-specific checks
-  if (check.app_router_only && !html.includes('__next')) {
-    return false;
-  }
-  if (check.pages_router_only && html.includes('__next')) {
-    return false;
-  }
-
-  const detection = check.detection;
-  if (!detection) {
-    // No detection rules, check is informational only
-    return false;
-  }
-
-  // Check HTML patterns
-  if (detection.html_patterns) {
-    for (const pattern of detection.html_patterns) {
-      if (html.includes(pattern)) {
-        return true;
-      }
-    }
-  }
-
-  // Check for missing content (SPA detection)
-  if (detection.missing_content) {
-    const bodyMatch = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
-    if (bodyMatch) {
-      const bodyContent = bodyMatch[1]
-        .replace(/<script[\s\S]*?<\/script>/gi, '')
-        .replace(/<style[\s\S]*?<\/style>/gi, '')
-        .replace(/<[^>]+>/g, '')
-        .replace(/\s+/g, ' ')
-        .trim();
-
-      // Less than 100 chars of text content = likely empty SPA
-      if (bodyContent.length < 100) {
-        return true;
-      }
-    }
-  }
-
-  // Check title in JS but not in HTML
-  if (detection.title_in_js && detection.title_not_in_html) {
-    const hasHtmlTitle = /<title[^>]*>[^<]+<\/title>/i.test(html);
-    const hasJsTitle = /document\.title\s*=/.test(html) ||
-                       /useHead|Helmet|useSeoMeta/.test(html);
-    if (!hasHtmlTitle && hasJsTitle) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Get framework-specific suggestions for fixing issues
- */
-export async function getFrameworkSuggestions(
-  frameworkInfo: FrameworkInfo,
-  issueCode: string
-): Promise<string | null> {
-  const recipe = await loadRecipe(frameworkInfo.framework);
-  if (!recipe) return null;
-
-  const check = recipe.checks.find(c => c.code === issueCode);
-  if (check) {
-    return check.howToFix;
-  }
-
-  return null;
-}
-
-/**
- * Get all available checks for a framework
- */
-export async function getFrameworkChecks(
-  framework: Framework
-): Promise<FrameworkCheck[]> {
-  const recipe = await loadRecipe(framework);
-  if (!recipe) return [];
-  return recipe.checks;
-}
-
-/**
- * Get performance tips for a framework
- */
-export async function getPerformanceTips(
-  framework: Framework
-): Promise<string[]> {
-  const recipe = await loadRecipe(framework);
-  if (!recipe) return [];
-  return recipe.performance_tips || [];
-}
-
-/**
- * Get SEO challenges for a framework
- */
-export async function getSeoChallenges(
-  framework: Framework
-): Promise<string[]> {
-  const recipe = await loadRecipe(framework);
-  if (!recipe) return [];
-  return recipe.seo_challenges || [];
-}
-
-/**
- * Get migration paths from current framework
- */
-export async function getMigrationPaths(
-  framework: Framework
-): Promise<Record<string, { effort: string; benefits: string[]; guide?: string }>> {
-  const recipe = await loadRecipe(framework);
-  if (!recipe) return {};
-  return recipe.migration_paths || {};
-}
-
-/**
- * Get total number of framework-specific checks
- */
-export async function getTotalFrameworkChecks(): Promise<number> {
-  let total = 0;
-  for (const framework of Object.keys(RECIPES) as Framework[]) {
-    const recipe = await loadRecipe(framework);
-    if (recipe) {
-      total += recipe.checks.length;
-    }
-  }
-  return total;
-}
-
-/**
- * Get framework summary for display
- */
-export async function getFrameworkSummary(framework: Framework): Promise<{
-  name: string;
-  category: string;
-  ssrDefault: boolean;
-  checkCount: number;
-  strengths: string[];
-  challenges: string[];
-} | null> {
-  const recipe = await loadRecipe(framework);
-  if (!recipe) return null;
-
-  return {
-    name: recipe.display_name,
-    category: recipe.category,
-    ssrDefault: recipe.ssr_default,
-    checkCount: recipe.checks.length,
-    strengths: recipe.seo_strengths || [],
-    challenges: recipe.seo_challenges || [],
-  };
-}
-
-/**
- * Embed recipe content for bundling (called at build time)
- */
-export function embedRecipe(framework: Framework, content: string): void {
-  RECIPE_CONTENT[framework] = content;
-}