@rankcli/agent-runtime 0.0.1

package/src/test/integration-test.ts

@@ -0,0 +1,325 @@
+#!/usr/bin/env npx tsx
+/**
+ * Integration Test for SEO Audit Tool
+ *
+ * Tests the full workflow:
+ * 1. Detect framework
+ * 2. Run SEO audit
+ * 3. Generate fixes
+ * 4. Create conventional commits with co-author
+ *
+ * Usage:
+ *   npx tsx src/test/integration-test.ts [repo-path]
+ *
+ * Test repos in /workspace/test_repos/:
+ *   - html-portfolio (Pure HTML/CSS)
+ *   - astro-blog (Astro)
+ *   - hugo-xmin (Hugo)
+ *   - github-pages-site (Jekyll/GitHub Pages)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import {
+  formatSEOCommitMessage,
+  createSEOCommit,
+  generateCommitSummary,
+  detectGitHubPages,
+  isGitRepo,
+  type SEOFixCommit,
+  type CommitConfig,
+} from '../git/commit-helper.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Framework detection
+interface FrameworkInfo {
+  name: string;
+  type: 'static' | 'ssr' | 'spa';
+  configFiles: string[];
+  fixPattern: string;
+}
+
+const FRAMEWORKS: Record<string, FrameworkInfo> = {
+  astro: {
+    name: 'Astro',
+    type: 'static',
+    configFiles: ['astro.config.mjs', 'astro.config.ts', 'astro.config.js'],
+    fixPattern: 'src/components/BaseHead.astro',
+  },
+  sveltekit: {
+    name: 'SvelteKit',
+    type: 'ssr',
+    configFiles: ['svelte.config.js', 'svelte.config.ts'],
+    fixPattern: 'src/routes/+layout.svelte',
+  },
+  nextjs: {
+    name: 'Next.js',
+    type: 'ssr',
+    configFiles: ['next.config.js', 'next.config.ts', 'next.config.mjs'],
+    fixPattern: 'app/layout.tsx',
+  },
+  hugo: {
+    name: 'Hugo',
+    type: 'static',
+    configFiles: ['config.toml', 'config.yaml', 'hugo.toml', 'hugo.yaml'],
+    fixPattern: 'layouts/partials/head.html',
+  },
+  jekyll: {
+    name: 'Jekyll',
+    type: 'static',
+    configFiles: ['_config.yml', '_config.yaml'],
+    fixPattern: '_includes/head.html',
+  },
+  html: {
+    name: 'Static HTML',
+    type: 'static',
+    configFiles: [],
+    fixPattern: 'index.html',
+  },
+};
+
+function detectFramework(repoPath: string): FrameworkInfo {
+  for (const [key, framework] of Object.entries(FRAMEWORKS)) {
+    if (key === 'html') continue; // Fallback
+
+    for (const configFile of framework.configFiles) {
+      if (fs.existsSync(path.join(repoPath, configFile))) {
+        return framework;
+      }
+    }
+  }
+
+  return FRAMEWORKS.html;
+}
+
+// Mock SEO audit results for testing
+interface MockAuditResult {
+  category: string;
+  issues: Array<{
+    code: string;
+    title: string;
+    severity: 'error' | 'warning' | 'notice';
+    affectedFiles: string[];
+  }>;
+}
+
+function getMockAuditResults(framework: FrameworkInfo): MockAuditResult[] {
+  // These simulate what a real audit would find
+  return [
+    {
+      category: 'on-page',
+      issues: [
+        {
+          code: 'TITLE_MISSING',
+          title: 'Missing title tag',
+          severity: 'error',
+          affectedFiles: [framework.fixPattern],
+        },
+        {
+          code: 'META_DESC_MISSING',
+          title: 'Missing meta description',
+          severity: 'error',
+          affectedFiles: [framework.fixPattern],
+        },
+      ],
+    },
+    {
+      category: 'social-meta',
+      issues: [
+        {
+          code: 'OG_TITLE_MISSING',
+          title: 'Missing Open Graph title',
+          severity: 'warning',
+          affectedFiles: [framework.fixPattern],
+        },
+        {
+          code: 'TWITTER_CARD_MISSING',
+          title: 'Missing Twitter Card meta tags',
+          severity: 'warning',
+          affectedFiles: [framework.fixPattern],
+        },
+      ],
+    },
+    {
+      category: 'crawlability',
+      issues: [
+        {
+          code: 'ROBOTS_TXT_MISSING',
+          title: 'Missing robots.txt',
+          severity: 'warning',
+          affectedFiles: ['robots.txt'],
+        },
+        {
+          code: 'SITEMAP_MISSING',
+          title: 'Missing sitemap.xml',
+          severity: 'warning',
+          affectedFiles: ['sitemap.xml'],
+        },
+      ],
+    },
+    {
+      category: 'structured-data',
+      issues: [
+        {
+          code: 'SCHEMA_MISSING',
+          title: 'No structured data found',
+          severity: 'warning',
+          affectedFiles: [framework.fixPattern],
+        },
+      ],
+    },
+  ];
+}
+
+// Generate mock fixes for testing
+function generateMockFixes(auditResults: MockAuditResult[]): SEOFixCommit[] {
+  return auditResults.map(result => ({
+    category: result.category,
+    issues: result.issues.map(i => i.code),
+    filesChanged: [...new Set(result.issues.flatMap(i => i.affectedFiles))],
+    description: `add ${result.category.replace('-', ' ')} improvements`,
+  }));
+}
+
+// Main test function
+async function runIntegrationTest(repoPath: string, options: { dryRun?: boolean } = {}) {
+  console.log('═'.repeat(60));
+  console.log('SEO AUDIT TOOL - INTEGRATION TEST');
+  console.log('═'.repeat(60));
+  console.log('');
+
+  // Validate repo path
+  if (!fs.existsSync(repoPath)) {
+    console.error(`❌ Repository not found: ${repoPath}`);
+    process.exit(1);
+  }
+
+  console.log(`📁 Repository: ${repoPath}`);
+
+  // Check if it's a git repo
+  const gitStatus = isGitRepo(repoPath);
+  console.log(`📋 Git repo: ${gitStatus ? 'Yes' : 'No'}`);
+
+  // Detect GitHub Pages
+  const ghPages = detectGitHubPages(repoPath);
+  if (ghPages.isGitHubPages) {
+    console.log(`🌐 GitHub Pages: Yes (${ghPages.type})`);
+    if (ghPages.baseUrl) {
+      console.log(`   Base URL: ${ghPages.baseUrl}`);
+    }
+  } else {
+    console.log('🌐 GitHub Pages: No');
+  }
+
+  // Detect framework
+  const framework = detectFramework(repoPath);
+  console.log(`🔧 Framework: ${framework.name} (${framework.type})`);
+  console.log(`📄 Fix target: ${framework.fixPattern}`);
+  console.log('');
+
+  // Run mock audit
+  console.log('─'.repeat(60));
+  console.log('RUNNING SEO AUDIT...');
+  console.log('─'.repeat(60));
+
+  const auditResults = getMockAuditResults(framework);
+  let totalIssues = 0;
+
+  for (const result of auditResults) {
+    console.log(`\n📊 ${result.category.toUpperCase()}`);
+    for (const issue of result.issues) {
+      const icon = issue.severity === 'error' ? '❌' : issue.severity === 'warning' ? '⚠️' : 'ℹ️';
+      console.log(`   ${icon} ${issue.code}: ${issue.title}`);
+      totalIssues++;
+    }
+  }
+
+  console.log(`\n📈 Total issues found: ${totalIssues}`);
+  console.log('');
+
+  // Generate fixes
+  console.log('─'.repeat(60));
+  console.log('GENERATING FIXES...');
+  console.log('─'.repeat(60));
+
+  const fixes = generateMockFixes(auditResults);
+
+  for (const fix of fixes) {
+    console.log(`\n🔨 ${fix.category}`);
+    console.log(`   Description: ${fix.description}`);
+    console.log(`   Files: ${fix.filesChanged.join(', ')}`);
+    console.log(`   Issues: ${fix.issues.join(', ')}`);
+  }
+  console.log('');
+
+  // Create commits
+  console.log('─'.repeat(60));
+  console.log('CREATING COMMITS...');
+  console.log('─'.repeat(60));
+  console.log('');
+
+  const commitConfig: CommitConfig = {
+    systemName: process.env.SEO_SYSTEM_NAME || 'SEO Autopilot',
+    systemEmail: process.env.SEO_SYSTEM_EMAIL || 'bot@seo-autopilot.dev',
+    dryRun: options.dryRun ?? true, // Default to dry run for safety
+  };
+
+  console.log(`🤖 Co-author: ${commitConfig.systemName} <${commitConfig.systemEmail}>`);
+  console.log(`🏃 Mode: ${commitConfig.dryRun ? 'DRY RUN' : 'LIVE'}`);
+  console.log('');
+
+  for (const fix of fixes) {
+    const message = formatSEOCommitMessage(fix, commitConfig);
+    console.log('┌' + '─'.repeat(58) + '┐');
+    console.log('│ COMMIT MESSAGE' + ' '.repeat(43) + '│');
+    console.log('├' + '─'.repeat(58) + '┤');
+    for (const line of message.split('\n')) {
+      const paddedLine = line.padEnd(56).slice(0, 56);
+      console.log(`│ ${paddedLine} │`);
+    }
+    console.log('└' + '─'.repeat(58) + '┘');
+    console.log('');
+  }
+
+  // Summary
+  console.log('─'.repeat(60));
+  console.log('SUMMARY');
+  console.log('─'.repeat(60));
+  console.log('');
+  console.log(`✅ Framework detected: ${framework.name}`);
+  console.log(`✅ GitHub Pages: ${ghPages.isGitHubPages ? 'Yes' : 'No'}`);
+  console.log(`✅ Issues found: ${totalIssues}`);
+  console.log(`✅ Commits prepared: ${fixes.length}`);
+  console.log('');
+
+  if (commitConfig.dryRun) {
+    console.log('💡 Run with --live to create actual commits');
+  }
+
+  return {
+    framework,
+    ghPages,
+    auditResults,
+    fixes,
+    totalIssues,
+  };
+}
+
+// CLI entry point
+const args = process.argv.slice(2);
+const repoPath = args[0] || path.join(__dirname, '../../../../test_repos/html-portfolio');
+const isLive = args.includes('--live');
+
+runIntegrationTest(repoPath, { dryRun: !isLive })
+  .then(() => {
+    console.log('═'.repeat(60));
+    console.log('TEST COMPLETE');
+    console.log('═'.repeat(60));
+  })
+  .catch((error) => {
+    console.error('Test failed:', error);
+    process.exit(1);
+  });

package/src/tools/analyzer.ts

@@ -0,0 +1,373 @@
+import { crawlUrl, extractMeta, analyzeHeadings, extractImages, extractLinks, extractSchema, checkRobots, checkSitemap } from './crawl.js';
+import type { SEOIssue, SEOAnalysisResult, MetaData, HeadingStructure, ImageInfo, ToolResult } from '../types.js';
+
+export async function analyzeUrl(params: { url: string }): Promise<ToolResult> {
+  const { url } = params;
+  const issues: SEOIssue[] = [];
+
+  try {
+    // Crawl the page
+    const crawlResult = await crawlUrl({ url });
+    if (!crawlResult.success || !crawlResult.data) {
+      return { success: false, error: `Failed to crawl URL: ${crawlResult.error}` };
+    }
+
+    const { html, statusCode, loadTime } = crawlResult.data as { html: string; statusCode: number; loadTime: number };
+
+    if (statusCode !== 200) {
+      issues.push({
+        severity: 'critical',
+        category: 'technical',
+        code: 'HTTP_ERROR',
+        message: `Page returned HTTP ${statusCode}`,
+        impact: 'Search engines cannot index pages that return error codes',
+      });
+    }
+
+    // Extract meta tags
+    const metaResult = await extractMeta({ html, url });
+    if (metaResult.success && metaResult.data) {
+      const meta = metaResult.data as MetaData;
+      analyzeMeta(meta, url, issues);
+    }
+
+    // Analyze headings
+    const headingsResult = await analyzeHeadings({ html });
+    if (headingsResult.success && headingsResult.data) {
+      const headings = headingsResult.data as HeadingStructure[];
+      analyzeHeadingStructure(headings, issues);
+    }
+
+    // Extract and analyze images
+    const imagesResult = await extractImages({ html });
+    if (imagesResult.success && imagesResult.data) {
+      const images = imagesResult.data as ImageInfo[];
+      analyzeImages(images, issues);
+    }
+
+    // Extract schema
+    const schemaResult = await extractSchema({ html });
+    if (schemaResult.success) {
+      const schemas = schemaResult.data as { type: string; data: unknown }[];
+      if (!schemas || schemas.length === 0) {
+        issues.push({
+          severity: 'warning',
+          category: 'schema',
+          code: 'MISSING_SCHEMA',
+          message: 'No JSON-LD structured data found',
+          impact: 'Missing rich snippets in search results. Add Schema.org markup for your content type.',
+        });
+      }
+    }
+
+    // Check robots.txt
+    const robotsResult = await checkRobots({ url });
+    if (robotsResult.success) {
+      const robots = robotsResult.data as { exists: boolean };
+      if (!robots.exists) {
+        issues.push({
+          severity: 'warning',
+          category: 'technical',
+          code: 'MISSING_ROBOTS',
+          message: 'No robots.txt file found',
+          impact: 'Provide crawling instructions to search engines with robots.txt',
+        });
+      }
+    }
+
+    // Check sitemap
+    const sitemapResult = await checkSitemap({ url });
+    if (sitemapResult.success) {
+      const sitemap = sitemapResult.data as { exists: boolean };
+      if (!sitemap.exists) {
+        issues.push({
+          severity: 'warning',
+          category: 'technical',
+          code: 'MISSING_SITEMAP',
+          message: 'No sitemap.xml found',
+          impact: 'Sitemap helps search engines discover and index all your pages',
+        });
+      }
+    }
+
+    // Performance check
+    if (loadTime > 3000) {
+      issues.push({
+        severity: loadTime > 5000 ? 'critical' : 'warning',
+        category: 'performance',
+        code: 'SLOW_LOAD_TIME',
+        message: `Page load time is ${(loadTime / 1000).toFixed(1)}s`,
+        impact: 'Slow pages hurt user experience and search rankings. Target <2.5s LCP.',
+      });
+    }
+
+    // Calculate score
+    const score = calculateScore(issues);
+
+    const result: SEOAnalysisResult = {
+      url,
+      score,
+      issues,
+      recommendations: generateRecommendations(issues),
+    };
+
+    return { success: true, data: result };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Analysis failed'
+    };
+  }
+}
+
+function analyzeMeta(meta: MetaData, url: string, issues: SEOIssue[]): void {
+  // Title
+  if (!meta.title) {
+    issues.push({
+      severity: 'critical',
+      category: 'meta',
+      code: 'MISSING_TITLE',
+      message: 'Missing title tag',
+      impact: 'Title is the most important on-page SEO element. Every page needs a unique title.',
+      fix: {
+        file: 'index.html',
+        before: null,
+        after: '<title>Your Page Title - Brand Name</title>',
+      }
+    });
+  } else if (meta.title.length < 30) {
+    issues.push({
+      severity: 'warning',
+      category: 'meta',
+      code: 'TITLE_TOO_SHORT',
+      message: `Title too short (${meta.title.length} chars)`,
+      impact: 'Longer titles provide more context. Aim for 50-60 characters.',
+      element: meta.title,
+    });
+  } else if (meta.title.length > 60) {
+    issues.push({
+      severity: 'warning',
+      category: 'meta',
+      code: 'TITLE_TOO_LONG',
+      message: `Title too long (${meta.title.length} chars)`,
+      impact: 'Titles over 60 characters get truncated in search results.',
+      element: meta.title.substring(0, 60) + '...',
+    });
+  }
+
+  // Meta description
+  if (!meta.description) {
+    issues.push({
+      severity: 'critical',
+      category: 'meta',
+      code: 'MISSING_META_DESC',
+      message: 'Missing meta description',
+      impact: 'Meta description appears in search results and affects click-through rate.',
+      fix: {
+        file: 'index.html',
+        before: null,
+        after: '<meta name="description" content="A compelling description of your page in 150-160 characters." />',
+      }
+    });
+  } else if (meta.description.length < 120) {
+    issues.push({
+      severity: 'warning',
+      category: 'meta',
+      code: 'META_DESC_TOO_SHORT',
+      message: `Meta description too short (${meta.description.length} chars)`,
+      impact: 'Aim for 150-160 characters for optimal display in search results.',
+    });
+  } else if (meta.description.length > 160) {
+    issues.push({
+      severity: 'info',
+      category: 'meta',
+      code: 'META_DESC_TOO_LONG',
+      message: `Meta description may be truncated (${meta.description.length} chars)`,
+      impact: 'Descriptions over 160 characters may be cut off in search results.',
+    });
+  }
+
+  // Canonical URL
+  if (!meta.canonical) {
+    issues.push({
+      severity: 'warning',
+      category: 'technical',
+      code: 'MISSING_CANONICAL',
+      message: 'No canonical URL specified',
+      impact: 'Canonical tags prevent duplicate content issues.',
+      fix: {
+        file: 'index.html',
+        before: null,
+        after: `<link rel="canonical" href="${url}" />`,
+      }
+    });
+  }
+
+  // Viewport
+  if (!meta.viewport) {
+    issues.push({
+      severity: 'critical',
+      category: 'technical',
+      code: 'MISSING_VIEWPORT',
+      message: 'Missing viewport meta tag',
+      impact: 'Required for mobile-friendly pages. Google uses mobile-first indexing.',
+      fix: {
+        file: 'index.html',
+        before: null,
+        after: '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+      }
+    });
+  }
+
+  // Open Graph
+  const missingOG: string[] = [];
+  if (!meta.openGraph.title) missingOG.push('og:title');
+  if (!meta.openGraph.description) missingOG.push('og:description');
+  if (!meta.openGraph.image) missingOG.push('og:image');
+
+  if (missingOG.length > 0) {
+    issues.push({
+      severity: 'warning',
+      category: 'social',
+      code: 'MISSING_OG_TAGS',
+      message: `Missing Open Graph tags: ${missingOG.join(', ')}`,
+      impact: 'Open Graph tags control how your page appears when shared on social media.',
+    });
+  }
+
+  // Twitter Card
+  if (!meta.twitter.card) {
+    issues.push({
+      severity: 'info',
+      category: 'social',
+      code: 'MISSING_TWITTER_CARD',
+      message: 'Missing Twitter Card meta tags',
+      impact: 'Twitter/X cards improve visibility when your content is shared.',
+    });
+  }
+}
+
+function analyzeHeadingStructure(headings: HeadingStructure[], issues: SEOIssue[]): void {
+  const h1s = headings.filter(h => h.level === 1);
+
+  if (h1s.length === 0) {
+    issues.push({
+      severity: 'critical',
+      category: 'content',
+      code: 'MISSING_H1',
+      message: 'No H1 heading found',
+      impact: 'Every page should have exactly one H1 that describes the main content.',
+    });
+  } else if (h1s.length > 1) {
+    issues.push({
+      severity: 'warning',
+      category: 'content',
+      code: 'MULTIPLE_H1',
+      message: `Multiple H1 headings found (${h1s.length})`,
+      impact: 'Best practice is one H1 per page. Use H2-H6 for subsections.',
+      element: h1s.map(h => h.text).join(', '),
+    });
+  }
+
+  // Check for skipped heading levels
+  let prevLevel = 0;
+  for (const h of headings) {
+    if (h.level > prevLevel + 1 && prevLevel > 0) {
+      issues.push({
+        severity: 'info',
+        category: 'content',
+        code: 'SKIPPED_HEADING_LEVEL',
+        message: `Skipped heading level: H${prevLevel} to H${h.level}`,
+        impact: 'Maintain proper heading hierarchy for accessibility and SEO.',
+      });
+      break; // Only report once
+    }
+    prevLevel = h.level;
+  }
+}
+
+function analyzeImages(images: ImageInfo[], issues: SEOIssue[]): void {
+  const missingAlt = images.filter(img => !img.alt);
+
+  if (missingAlt.length > 0) {
+    issues.push({
+      severity: 'warning',
+      category: 'accessibility',
+      code: 'IMAGES_MISSING_ALT',
+      message: `${missingAlt.length} image(s) missing alt text`,
+      impact: 'Alt text is essential for accessibility and helps search engines understand images.',
+      element: missingAlt.slice(0, 3).map(i => i.src).join(', '),
+    });
+  }
+
+  const missingDimensions = images.filter(img => !img.width || !img.height);
+  if (missingDimensions.length > 0) {
+    issues.push({
+      severity: 'info',
+      category: 'performance',
+      code: 'IMAGES_MISSING_DIMENSIONS',
+      message: `${missingDimensions.length} image(s) missing width/height`,
+      impact: 'Specifying dimensions prevents layout shift (CLS).',
+    });
+  }
+}
+
+function calculateScore(issues: SEOIssue[]): number {
+  const weights = {
+    critical: 15,
+    warning: 5,
+    info: 1,
+  };
+
+  let totalDeduction = 0;
+  for (const issue of issues) {
+    totalDeduction += weights[issue.severity];
+  }
+
+  return Math.max(0, Math.min(100, 100 - totalDeduction));
+}
+
+function generateRecommendations(issues: SEOIssue[]) {
+  const recommendations = [];
+
+  const criticalCount = issues.filter(i => i.severity === 'critical').length;
+  const warningCount = issues.filter(i => i.severity === 'warning').length;
+
+  if (criticalCount > 0) {
+    recommendations.push({
+      priority: 'high' as const,
+      category: 'immediate',
+      message: `Fix ${criticalCount} critical issue(s) first`,
+      impact: 'Critical issues directly impact search visibility',
+    });
+  }
+
+  if (issues.some(i => i.code === 'MISSING_SCHEMA')) {
+    recommendations.push({
+      priority: 'high' as const,
+      category: 'schema',
+      message: 'Add JSON-LD structured data',
+      impact: 'Enable rich snippets in search results',
+    });
+  }
+
+  if (issues.some(i => i.code.includes('OG') || i.code.includes('TWITTER'))) {
+    recommendations.push({
+      priority: 'medium' as const,
+      category: 'social',
+      message: 'Complete social media meta tags',
+      impact: 'Improve appearance when shared on social platforms',
+    });
+  }
+
+  if (warningCount > 3) {
+    recommendations.push({
+      priority: 'medium' as const,
+      category: 'optimization',
+      message: `Address ${warningCount} warnings to improve score`,
+      impact: 'Each fix improves overall SEO health',
+    });
+  }
+
+  return recommendations;
+}