@rankcli/agent-runtime 0.0.8 → 0.0.11

package/README.md

@@ -1,241 +1,135 @@
 # @rankcli/agent-runtime
 
-Core audit engine for RankCLI. Runs 280+ SEO checks and powers both the CLI and SaaS edge functions.
+Core SEO engine for RankCLI. 280+ checks, 7 deep analyzers, framework-specific fix generation.
 
-## Architecture
-
-This package is **isomorphic** - it works in both Node.js and Deno environments:
-
-- **Node.js**: Used by the CLI (`packages/cli`)
-- **Deno**: Used by Supabase Edge Functions (`packages/saas/supabase/functions`)
-
-The isomorphic design uses native `fetch` API instead of Node-specific modules like `axios` or `https`.
+## Features
 
-## Directory Structure
+### 🤖 GEO (Generative Engine Optimization)
+First SEO engine with AI search optimization:
+- AI crawler detection (GPTBot, ClaudeBot, PerplexityBot, etc.)
+- JS rendering analysis for AI crawlers
+- LLM-friendliness scoring
+- Citation readiness analysis
 
-```
-src/
-├── audit/
-│   ├── engine.ts          # Main audit orchestrator
-│   ├── types.ts           # Issue definitions & types
-│   ├── deno-entry.ts      # Deno-specific entry point
-│   └── checks/            # Individual check modules
-│       ├── crawlability.ts
-│       ├── on-page.ts
-│       ├── performance.ts
-│       ├── security.ts
-│       ├── ai-readiness.ts
-│       └── ... (40+ check modules)
-├── utils/
-│   └── http.ts            # Isomorphic HTTP utilities
-├── content/               # Content generation
-├── geo/                   # GEO tracking
-├── git/                   # Git/PR helpers
-└── index.ts               # Main entry point
+### 📊 7 Deep Analyzers
+```typescript
+import { analyzers } from '@rankcli/agent-runtime';
+
+// Comprehensive analysis
+const result = await analyzers.analyzeComprehensive(html, url);
+
+// Individual analyzers
+const geo = await analyzers.analyzeGEO(html, url, robotsTxt);
+const cwv = analyzers.analyzeCoreWebVitals(html, url);
+const security = analyzers.analyzeSecurityHeaders(headers, url);
+const schema = analyzers.analyzeStructuredData(html, url);
+const images = analyzers.analyzeImages(html, url);
+const links = analyzers.analyzeInternalLinking(html, url);
+const mobile = analyzers.analyzeMobileSEO(html, url);
 ```
 
-## Development
-
-### Prerequisites
-
-- Node.js 18+
-- pnpm
+| Analyzer | Checks |
+|----------|--------|
+| **GEO** | AI crawler access, robots.txt, SSR detection, LLM signals |
+| **Core Web Vitals** | LCP, CLS, INP, TTFB estimation |
+| **Security** | HTTPS, HSTS, CSP, grades A+ to F |
+| **Structured Data** | JSON-LD validation, rich results |
+| **Images** | Alt text, dimensions, formats, lazy loading |
+| **Internal Links** | Anchor text, orphan detection |
+| **Mobile** | Viewport, touch targets, PWA |
 
-### Commands
-
-```bash
-# Install dependencies
-pnpm install
+### 🔧 Framework-Specific Fixes
 
-# Development mode (watches both Node and Deno bundles)
-pnpm dev
+Auto-generate SEO fixes for 25+ frameworks:
 
-# Run tests
-pnpm test        # Watch mode
-pnpm test:run    # Single run
-
-# Build for production
-pnpm build       # Builds Node.js + Deno bundles
+```typescript
+import { generateFrameworkFix } from '@rankcli/agent-runtime';
 
-# Build only Deno bundle
-pnpm build:deno
+const fix = generateFrameworkFix({
+  framework: 'nextjs-app',
+  issue: { code: 'MISSING_TITLE', ... },
+  siteMeta: { title: 'My Site', description: '...' }
+});
 ```
 
-### Development Workflow
-
-When you run `pnpm dev`, it:
-
-1. Builds the Deno bundle first
-2. Starts tsup in watch mode for Node.js
-3. Rebuilds the Deno bundle on every successful Node.js build
-
-This ensures both the CLI (Node.js) and edge functions (Deno) stay in sync during development.
+**Supported:**
+- React, Next.js, Vue, Nuxt, Angular, Svelte, SvelteKit, Astro, Remix, Gatsby, Solid.js, Qwik
+- Rails, Django, Laravel, Spring Boot, ASP.NET Core, Phoenix, Go
+- Hugo, Jekyll, Eleventy, Pelican
+- HTMX, Hotwire/Turbo
 
-### Available Scripts
-
-| Script | Description |
-|--------|-------------|
-| `pnpm dev` | Watch mode - rebuilds Node + Deno on changes |
-| `pnpm dev:node` | Watch mode - Node.js only |
-| `pnpm dev:deno` | Watch mode - Deno bundle only |
-| `pnpm build` | Production build (Node.js + Deno) |
-| `pnpm build:deno` | Build Deno bundle only |
-| `pnpm test` | Run tests in watch mode |
-| `pnpm test:run` | Run tests once |
+## Architecture
 
-## Deno Bundle
+Isomorphic engine - works in Node.js, Deno, and WASM:
 
-The Deno bundle is generated at:
-```
-packages/saas/supabase/functions/_shared/audit/
-├── engine.bundle.js   # Bundled audit engine
-└── index.ts           # Wrapper with cheerio import
 ```
-
-Edge functions import from the shared bundle:
-```typescript
-import { runFullAudit } from '../_shared/audit/index.ts';
+src/
+├── analyzers/          # 7 deep analyzers (GEO, CWV, etc.)
+├── audit/              # 280+ individual checks
+├── fixer/              # Framework-specific fix generation
+├── frameworks/         # Framework detection
+├── content/            # Content analysis
+├── geo/                # GEO tracking
+├── git/                # PR/commit helpers
+└── index.ts
 ```
 
-### How It Works
+## Installation
 
-1. `scripts/build-deno.ts` uses esbuild to bundle `src/audit/deno-entry.ts`
-2. The bundle excludes `cheerio` (imported from esm.sh at runtime)
-3. Node-specific APIs are polyfilled or replaced with web-compatible alternatives
-
-### Isomorphic Considerations
-
-When adding new features to the audit engine:
-
-- Use `fetch` instead of `axios` or Node's `http`/`https`
-- Use the helpers in `src/utils/http.ts` for HTTP requests
-- Avoid Node-specific modules (`fs`, `path`, `dns`, `crypto`, etc.)
-- For DNS lookups, use DNS-over-HTTPS (see `additional-checks.ts`)
-- Test in both Node.js (`pnpm test`) and edge functions
-
-## VS Code Tasks
-
-If using VS Code, these tasks are available (Cmd/Ctrl+Shift+P → "Tasks: Run Task"):
-
-| Task | Description |
-|------|-------------|
-| Dev: Agent Runtime (with Deno watch) | Watches and rebuilds both bundles |
-| Dev: SaaS Frontend | Runs the Vite dev server |
-| Dev: Full Stack | Runs both in parallel |
-| Build: Deno Bundle | One-time Deno bundle build |
-| Deploy: Edge Functions | Deploys to Supabase |
-
-## DevContainer
-
-When using the devcontainer:
-
-- The Deno bundle is built automatically on container creation
-- Run `pnpm dev` in `packages/agent-runtime` to start watching for changes
-- The bundle is rebuilt automatically when you modify audit code
-
-## API
+```bash
+pnpm add @rankcli/agent-runtime
+```
 
-### runFullAudit
+## Usage
 
-Main entry point for running audits:
+### Full Audit
 
 ```typescript
-import { runFullAudit } from '@rankcli/agent-runtime';
+import { runAudit, generateFixes } from '@rankcli/agent-runtime';
 
-const report = await runFullAudit('https://example.com', {
-  maxPages: 10,           // Max pages to crawl
-  includeAdvanced: true,  // Run advanced checks
-  includeAI: false,       // Run AI-powered analysis
+const audit = await runAudit({
+  url: 'https://example.com',
+  maxPages: 5,
+  options: { geo: true }
 });
 
-console.log(report.overallScore);      // 0-100
-console.log(report.issues);            // Array of issues
-console.log(report.healthScores);      // Category scores
-console.log(report.checksRun);         // Number of checks run
+const fixes = await generateFixes(audit.issues);
 ```
 
-### Issue Structure
+### Generate AI-Friendly robots.txt
 
 ```typescript
-interface AuditIssue {
-  code: string;           // e.g., 'TITLE_MISSING'
-  severity: 'error' | 'warning' | 'notice';
-  category: string;       // e.g., 'on-page', 'security'
-  title: string;          // Human-readable title
-  description?: string;   // Detailed description
-  impact?: string;        // SEO impact explanation
-  howToFix?: string;      // Fix instructions
-  affectedUrls?: string[];
-  details?: Record<string, unknown>;
-}
-```
-
-### Health Scores
+import { analyzers } from '@rankcli/agent-runtime';
 
-```typescript
-interface HealthScores {
-  crawlability: number;   // 0-100
-  onPage: number;
-  content: number;
-  performance: number;
-  security: number;
-  socialMeta: number;
-  aiReadiness: number;
-  mobile: number;
-}
+const robotsTxt = analyzers.generateAIFriendlyRobotsTxt('https://example.com');
 ```
 
-## Adding New Checks
-
-1. Create a new file in `src/audit/checks/` or add to an existing one
-2. Export the check function
-3. Add to `src/audit/engine.ts` to include in the audit flow
-4. Add to `src/audit/deno-entry.ts` to export for Deno
-5. Run `pnpm build:deno` to regenerate the bundle
-6. Add tests in a `.test.ts` file
-
-Example check:
+### Generate Schema Templates
 
 ```typescript
-// src/audit/checks/my-check.ts
-import { httpGet } from '../../utils/http.js';
-import type { AuditIssue } from '../types.js';
-
-export async function checkMyThing(url: string): Promise<AuditIssue[]> {
-  const issues: AuditIssue[] = [];
-
-  const response = await httpGet(url);
-
-  if (/* condition */) {
-    issues.push({
-      code: 'MY_ISSUE_CODE',
-      severity: 'warning',
-      category: 'my-category',
-      title: 'Issue title',
-      description: 'What this means',
-      howToFix: 'How to fix it',
-      affectedUrls: [url],
-    });
-  }
-
-  return issues;
-}
-```
+import { analyzers } from '@rankcli/agent-runtime';
 
-## Testing
+const schema = analyzers.generateSchemaTemplate('article', {
+  siteName: 'My Blog',
+  siteUrl: 'https://myblog.com',
+  authorName: 'John Doe'
+});
+```
 
-Tests use Vitest:
+## Development
 
 ```bash
-# Run all tests
-pnpm test:run
+pnpm install
+pnpm dev        # Watch mode
+pnpm test       # Run tests
+pnpm build      # Build Node.js + Deno
+```
 
-# Run specific test file
-pnpm test:run src/audit/checks/social-meta.test.ts
+## Related
 
-# Run with coverage
-pnpm test:coverage
-```
+- [@rankcli/cli](../cli) - Command-line interface
+- [@rankcli/mcp-server](../mcp-server) - MCP server for AI assistants
+- [rankcli.dev](https://rankcli.dev) - Documentation
 
 ## License
 

package/dist/analyzer-GMURJADU.mjs

@@ -0,0 +1,7 @@
+import {
+  analyzeUrl
+} from "./chunk-PJLNXOLN.mjs";
+import "./chunk-6BWS3CLP.mjs";
+export {
+  analyzeUrl
+};

package/dist/chunk-2JADKV3Z.mjs

@@ -0,0 +1,244 @@
+// src/analyzers/image-optimization-analyzer.ts
+import * as cheerio from "cheerio";
+var MODERN_FORMATS = ["webp", "avif"];
+var LEGACY_FORMATS = ["jpg", "jpeg", "png", "gif", "bmp"];
+var MAX_RECOMMENDED_DIMENSION = 2e3;
+function getImageFormat(src) {
+  if (src.startsWith("data:image/")) {
+    const match = src.match(/data:image\/(\w+)/);
+    return match ? match[1] : void 0;
+  }
+  try {
+    const url = new URL(src, "https://example.com");
+    const pathname = url.pathname.toLowerCase();
+    const ext = pathname.split(".").pop();
+    return ext && ext.length <= 5 ? ext : void 0;
+  } catch {
+    const ext = src.split(".").pop()?.toLowerCase();
+    return ext && ext.length <= 5 ? ext : void 0;
+  }
+}
+function analyzeImages(html, url) {
+  const $ = cheerio.load(html);
+  const issues = [];
+  const recommendations = [];
+  let score = 100;
+  const allImages = [];
+  const missingAlt = [];
+  const oversizedImages = [];
+  const decorativeWithoutRole = [];
+  let imagesWithAlt = 0;
+  let imagesWithDimensions = 0;
+  let imagesWithLazyLoading = 0;
+  let modernFormats = 0;
+  let legacyFormats = 0;
+  $("img").each((_, el) => {
+    const $img = $(el);
+    const src = $img.attr("src") || $img.attr("data-src") || "";
+    const alt = $img.attr("alt");
+    const width = parseInt($img.attr("width") || "0");
+    const height = parseInt($img.attr("height") || "0");
+    const loading = $img.attr("loading");
+    const role = $img.attr("role");
+    const format = getImageFormat(src);
+    const imageIssues = [];
+    const imgInfo = {
+      src: src.substring(0, 200),
+      // Truncate long data URLs
+      alt,
+      width: width || void 0,
+      height: height || void 0,
+      format,
+      loading,
+      issues: imageIssues
+    };
+    if (alt === void 0) {
+      imageIssues.push("Missing alt attribute");
+      missingAlt.push(imgInfo);
+    } else if (alt === "") {
+      if (role !== "presentation" && role !== "none") {
+        imageIssues.push('Empty alt without role="presentation"');
+        decorativeWithoutRole.push(imgInfo);
+      }
+      imagesWithAlt++;
+    } else {
+      imagesWithAlt++;
+      if (alt.toLowerCase().includes("image") || alt.toLowerCase().includes("picture") || alt.toLowerCase().includes("photo")) {
+        imageIssues.push("Alt text contains generic terms");
+      }
+      if (alt.length > 125) {
+        imageIssues.push("Alt text too long (>125 chars)");
+      }
+      if (/\.(jpg|jpeg|png|gif|webp|svg)$/i.test(alt)) {
+        imageIssues.push("Alt text appears to be a filename");
+      }
+    }
+    if (width > 0 && height > 0) {
+      imagesWithDimensions++;
+      if (width > MAX_RECOMMENDED_DIMENSION || height > MAX_RECOMMENDED_DIMENSION) {
+        imageIssues.push(`Dimensions too large (${width}x${height})`);
+        oversizedImages.push(imgInfo);
+      }
+    } else {
+      imageIssues.push("Missing width/height attributes");
+    }
+    if (loading === "lazy") {
+      imagesWithLazyLoading++;
+    }
+    if (format) {
+      if (MODERN_FORMATS.includes(format)) {
+        modernFormats++;
+      } else if (LEGACY_FORMATS.includes(format)) {
+        legacyFormats++;
+      }
+    }
+    allImages.push(imgInfo);
+  });
+  const totalImages = allImages.length;
+  if (missingAlt.length > 0) {
+    const percentage = Math.round(missingAlt.length / totalImages * 100);
+    const severity = percentage > 50 ? "critical" : percentage > 20 ? "warning" : "info";
+    issues.push({
+      code: "IMG_MISSING_ALT",
+      severity,
+      category: "content",
+      title: `${missingAlt.length} images missing alt attribute`,
+      description: `${percentage}% of images lack alt text, hurting accessibility and SEO.`,
+      impact: "Screen readers cannot describe images; search engines lose context",
+      howToFix: 'Add descriptive alt text to all images. Use alt="" for decorative images.',
+      affectedUrls: [url]
+    });
+    score -= Math.min(missingAlt.length * 3, 25);
+  }
+  const missingDimensions = totalImages - imagesWithDimensions;
+  if (missingDimensions > 0) {
+    issues.push({
+      code: "IMG_MISSING_DIMENSIONS",
+      severity: "warning",
+      category: "performance",
+      title: `${missingDimensions} images missing width/height`,
+      description: "Images without explicit dimensions cause layout shifts (CLS).",
+      impact: "Poor Core Web Vitals, degraded user experience",
+      howToFix: "Add width and height attributes to all images.",
+      affectedUrls: [url]
+    });
+    score -= Math.min(missingDimensions * 2, 20);
+  }
+  if (legacyFormats > 0 && modernFormats === 0) {
+    issues.push({
+      code: "IMG_NO_MODERN_FORMATS",
+      severity: "warning",
+      category: "performance",
+      title: "No modern image formats (WebP/AVIF)",
+      description: `All ${legacyFormats} images use legacy formats (JPEG/PNG).`,
+      impact: "Larger file sizes, slower page load",
+      howToFix: "Convert images to WebP or AVIF format. Use <picture> element for fallbacks.",
+      affectedUrls: [url]
+    });
+    score -= 10;
+    recommendations.push("Convert images to WebP/AVIF for 30-50% smaller file sizes");
+  }
+  if (oversizedImages.length > 0) {
+    issues.push({
+      code: "IMG_OVERSIZED",
+      severity: "warning",
+      category: "performance",
+      title: `${oversizedImages.length} images have excessive dimensions`,
+      description: `Images larger than ${MAX_RECOMMENDED_DIMENSION}px may be wasteful on most screens.`,
+      impact: "Unnecessary bandwidth usage, slower loading",
+      howToFix: "Resize images to match their display size. Use srcset for responsive images.",
+      affectedUrls: [url]
+    });
+    score -= Math.min(oversizedImages.length * 3, 15);
+  }
+  const firstImage = allImages[0];
+  if (firstImage?.loading === "lazy") {
+    issues.push({
+      code: "IMG_HERO_LAZY",
+      severity: "warning",
+      category: "performance",
+      title: 'First image has loading="lazy"',
+      description: "Above-the-fold images should not be lazy-loaded as it delays LCP.",
+      impact: "Slower Largest Contentful Paint",
+      howToFix: 'Remove loading="lazy" from hero/above-fold images. Keep it for below-fold images.',
+      affectedUrls: [url]
+    });
+    score -= 10;
+  }
+  const belowFoldWithoutLazy = allImages.slice(3).filter((img) => img.loading !== "lazy");
+  if (belowFoldWithoutLazy.length > 5) {
+    recommendations.push(`Consider adding loading="lazy" to ${belowFoldWithoutLazy.length} below-fold images`);
+  }
+  if (decorativeWithoutRole.length > 0) {
+    issues.push({
+      code: "IMG_DECORATIVE_NO_ROLE",
+      severity: "info",
+      category: "content",
+      title: `${decorativeWithoutRole.length} decorative images without role`,
+      description: 'Images with empty alt should have role="presentation" for accessibility.',
+      impact: "Minor accessibility issue",
+      howToFix: 'Add role="presentation" to decorative images with empty alt.',
+      affectedUrls: [url]
+    });
+  }
+  const elementsWithBgImage = $('[style*="background-image"], [style*="background:"]').length;
+  if (elementsWithBgImage > 3) {
+    recommendations.push(`${elementsWithBgImage} CSS background images detected - ensure they're not content images`);
+  }
+  const svgImages = $('svg, img[src$=".svg"]').length;
+  if (svgImages > 0) {
+  }
+  if (totalImages > 0 && imagesWithAlt === totalImages) {
+    recommendations.push("\u2713 All images have alt attributes");
+  }
+  if (modernFormats > legacyFormats) {
+    recommendations.push("\u2713 Majority of images use modern formats");
+  }
+  return {
+    score: Math.max(0, Math.min(100, score)),
+    totalImages,
+    imagesWithAlt,
+    imagesWithDimensions,
+    imagesWithLazyLoading,
+    modernFormats,
+    legacyFormats,
+    oversizedImages,
+    missingAlt,
+    decorativeWithoutRole,
+    issues,
+    recommendations
+  };
+}
+function generateResponsiveImage(options) {
+  const { src, alt, widths, sizes = "100vw", loading = "lazy", className } = options;
+  const basename = src.replace(/\.[^.]+$/, "");
+  const ext = src.split(".").pop() || "jpg";
+  const srcset = widths.map((w) => `${basename}-${w}w.webp ${w}w`).join(", ");
+  const fallbackSrcset = widths.map((w) => `${basename}-${w}w.${ext} ${w}w`).join(", ");
+  return `<picture>
+  <source
+    type="image/webp"
+    srcset="${srcset}"
+    sizes="${sizes}"
+  />
+  <source
+    type="image/${ext === "jpg" ? "jpeg" : ext}"
+    srcset="${fallbackSrcset}"
+    sizes="${sizes}"
+  />
+  <img
+    src="${src}"
+    alt="${alt}"
+    width="${widths[widths.length - 1]}"
+    height="auto"
+    loading="${loading}"${className ? `
+    class="${className}"` : ""}
+    decoding="async"
+  />
+</picture>`;
+}
+
+export {
+  analyzeImages,
+  generateResponsiveImage
+};