aeo-ready 1.1.0 → 1.3.0

package/src/scan.js

@@ -1,65 +1,38 @@
 import chalk from "chalk";
-import { fetchUrl, resolveUrl } from "./utils/fetch.js";
-import { detectSiteType } from "./utils/detect-type.js";
-import { runDiscoveryChecks } from "./checks/agent-readiness/discovery.js";
-import { runContentStructureChecks } from "./checks/agent-readiness/content-structure.js";
-import { runCapabilityChecks } from "./checks/agent-readiness/capability.js";
-import { runActionableChecks } from "./checks/agent-readiness/actionable.js";
-import { runStructuredDataChecks } from "./checks/ai-visibility/structured-data.js";
-import { runCitationReadinessChecks } from "./checks/ai-visibility/citation-readiness.js";
-import { runAuthorityChecks } from "./checks/ai-visibility/authority.js";
-import { runFreshnessChecks } from "./checks/ai-visibility/freshness.js";
 import { runAllBenchmarks, printBenchmarks } from "./benchmark/index.js";
 import { saveResult } from "./history/index.js";
 import { generateDashboard } from "./dashboard/generate.js";
-import { readdirSync, readFileSync, existsSync } from "fs";
-import { join } from "path";
 import { exec } from "child_process";
 
 export async function scan(opts) {
-  const { url, dir, json, benchmark } = opts;
-  const mode = url ? "url" : "repo";
+  const { url, dir, json } = opts;
 
   if (!json) {
     console.log(
-      chalk.bold("\n  aeo-ready") + chalk.dim(" — AI readiness audit\n"),
+      chalk.bold("\n  aeo-ready") + chalk.dim(" — AEO benchmark aggregator\n"),
     );
+    console.log(chalk.dim(`  Scanning ${url}...\n`));
   }
 
-  const context = await gatherContext(mode, url, dir);
-
-  if (!json) {
-    console.log(chalk.dim(`  Mode: ${mode} | Type: ${context.siteType}\n`));
-  }
-
-  const agentReadiness = await runAgentReadinessChecks(context);
-  const aiVisibility = await runAiVisibilityChecks(context);
-
-  const score = agentReadiness.score + aiVisibility.score;
-  const grade = scoreToGrade(score);
-
-  let benchmarkResult = null;
-  if (benchmark) {
-    benchmarkResult = await runAllBenchmarks(mode === "url" ? url : dir);
-  }
+  const benchmarks = await runAllBenchmarks(url, dir);
+  const scores = collectScores(benchmarks);
+  const averageScore =
+    scores.length > 0
+      ? Math.round(scores.reduce((s, v) => s + v, 0) / scores.length)
+      : 0;
 
   const result = {
-    score,
-    grade,
-    siteType: context.siteType,
-    mode,
-    target: url || dir,
+    url,
     timestamp: new Date().toISOString(),
-    agentReadiness,
-    aiVisibility,
-    benchmarks: benchmarkResult,
+    averageScore,
+    benchmarks,
   };
 
   if (!json) {
     printReport(result);
   }
 
-  const baseDir = dir || process.cwd();
+  const baseDir = process.cwd();
   await saveResult(result, baseDir);
 
   if (!json) {
@@ -71,278 +44,71 @@ export async function scan(opts) {
   return result;
 }
 
-async function gatherContext(mode, url, dir) {
-  const context = { mode, url, dir, pages: {}, files: [], html: "" };
-
-  if (mode === "url") {
-    const homepage = await fetchUrl(url);
-    context.html = homepage.text;
-    context.pages.home = homepage;
-
-    const fetches = [
-      fetchUrl(resolveUrl(url, "/llms.txt")),
-      fetchUrl(resolveUrl(url, "/robots.txt")),
-      fetchUrl(resolveUrl(url, "/sitemap.xml")),
-      fetchUrl(resolveUrl(url, "/.well-known/agent.json")),
-      fetchUrl(resolveUrl(url, "/openapi.json")),
-    ];
-
-    const [llms, robots, sitemap, agentJson, openapi] =
-      await Promise.all(fetches);
-    context.pages.llmsTxt = llms;
-    context.pages.robotsTxt = robots;
-    context.pages.sitemap = sitemap;
-    context.pages.agentJson = agentJson;
-    context.pages.openapi = openapi;
-  } else {
-    const fileList = listFiles(dir);
-    context.files = fileList;
-    context.fileContents = {};
-    for (const f of fileList) {
-      try {
-        context.fileContents[f] = readFileSync(join(dir, f), "utf8");
-      } catch {
-        /* skip binary/unreadable */
-      }
-    }
-    const indexHtml = [
-      "index.html",
-      "public/index.html",
-      "dist/index.html",
-    ].find((p) => existsSync(join(dir, p)));
-    if (indexHtml) {
-      context.html = readFileSync(join(dir, indexHtml), "utf8");
-    }
+function collectScores(benchmarks) {
+  const scores = [];
+  if (benchmarks.agenticSeo?.available) {
+    scores.push(benchmarks.agenticSeo.score);
   }
-
-  context.siteType = detectSiteType({
-    html: context.html,
-    files: context.files,
-    url,
-  });
-
-  return context;
-}
-
-function listFiles(dir) {
-  const skip = new Set([
-    "node_modules",
-    ".git",
-    "dist",
-    "build",
-    ".next",
-    ".venv",
-    "__pycache__",
-    "target",
-    ".aeo-ready",
-  ]);
-  const results = [];
-
-  function walk(current, prefix) {
-    let entries;
-    try {
-      entries = readdirSync(join(dir, current), { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      if (skip.has(entry.name)) continue;
-      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-      if (entry.isDirectory()) {
-        walk(join(current, entry.name), rel);
-      } else {
-        results.push(rel);
-      }
-    }
+  if (benchmarks.cloudflare?.available) {
+    scores.push(
+      Math.round(
+        (benchmarks.cloudflare.score / benchmarks.cloudflare.maxScore) * 100,
+      ),
+    );
   }
-
-  walk("", "");
-  return results;
-}
-
-async function runAgentReadinessChecks(context) {
-  const discovery = await runDiscoveryChecks(context);
-  const contentStructure = await runContentStructureChecks(context);
-  const capability = await runCapabilityChecks(context);
-  const actionable = await runActionableChecks(context);
-
-  const score =
-    discovery.score +
-    contentStructure.score +
-    capability.score +
-    actionable.score;
-
-  return {
-    score,
-    maxScore: 50,
-    categories: { discovery, contentStructure, capability, actionable },
-  };
-}
-
-async function runAiVisibilityChecks(context) {
-  const structuredData = await runStructuredDataChecks(context);
-  const citationReadiness = await runCitationReadinessChecks(context);
-  const authority = await runAuthorityChecks(context);
-  const freshness = await runFreshnessChecks(context);
-
-  const score =
-    structuredData.score +
-    citationReadiness.score +
-    authority.score +
-    freshness.score;
-
-  return {
-    score,
-    maxScore: 50,
-    categories: { structuredData, citationReadiness, authority, freshness },
-  };
-}
-
-function scoreToGrade(score) {
-  if (score >= 80) return "A";
-  if (score >= 65) return "B";
-  if (score >= 50) return "C";
-  if (score >= 35) return "D";
-  return "F";
+  if (benchmarks.fern?.available) {
+    scores.push(benchmarks.fern.score);
+  }
+  return scores;
 }
 
 function printReport(result) {
-  const { score, grade, agentReadiness, aiVisibility, benchmarks } = result;
+  const { benchmarks, averageScore } = result;
 
-  const gradeColor =
-    grade === "A"
-      ? chalk.green
-      : grade === "B"
-        ? chalk.cyan
-        : grade === "C"
-          ? chalk.yellow
-          : chalk.red;
-
-  console.log(
-    `  ${bar(score, 100, 40)}  ${gradeColor.bold(grade)} ${score}/100\n`,
-  );
+  printBenchmarks(benchmarks);
 
+  const gc =
+    averageScore >= 80
+      ? chalk.green
+      : averageScore >= 50
+        ? chalk.yellow
+        : chalk.red;
   console.log(
-    chalk.dim(
-      "  Agent Readiness — can AI agents find, read, and use your site?",
-    ),
+    chalk.dim("  ─────────────────────────────────────────────────\n"),
   );
   console.log(
-    chalk.dim(
-      "  AI Visibility — how accurately do AI search engines describe you?",
-    ),
+    `  Average across all sources: ${gc.bold(`${averageScore}/100`)}\n`,
   );
 
-  if (agentReadiness.score < 25) {
+  if (averageScore < 80) {
+    console.log(chalk.bold("  Fix it:\n"));
     console.log(
-      chalk.dim(
-        "\n  Agent Readiness is low — AI engines can't cite what they can't read.",
-      ),
+      chalk.dim("    npx agentic-seo init") +
+        "          scaffold llms.txt, AGENTS.md, skill.md",
     );
-    console.log(chalk.dim("  Fix the agent side first. Visibility follows."));
-  }
-  console.log("");
 
-  printScorecard("Agent Readiness", agentReadiness);
-  printScorecard("AI Visibility", aiVisibility);
-
-  const allChecks = [
-    ...Object.values(agentReadiness.categories),
-    ...Object.values(aiVisibility.categories),
-  ].flatMap((c) => c.checks);
-  const passed = allChecks.filter((c) => c.passed).length;
-  const failed = allChecks.filter((c) => !c.passed && c.points === 0).length;
-  const partial = allChecks.length - passed - failed;
-
-  console.log(
-    chalk.dim(
-      `  ${chalk.green(passed + " passed")} · ${partial ? chalk.yellow(partial + " partial") + " · " : ""}${chalk.red(failed + " failed")} · ${allChecks.length} checks total\n`,
-    ),
-  );
-
-  if (benchmarks) {
-    printBenchmarks(benchmarks);
-  }
-
-  if (failed + partial > 0) {
-    console.log(chalk.bold("  Next steps:\n"));
-    const topFixes = allChecks
-      .filter((c) => !c.passed && c.fix)
-      .sort(
-        (a, b) =>
-          b.maxPoints - (b.points || 0) - (a.maxPoints - (a.points || 0)),
-      )
-      .slice(0, 3);
-    for (const fix of topFixes) {
-      console.log(chalk.dim(`    - ${fix.fix}`));
+    const cfFails =
+      benchmarks.cloudflare?.checks?.filter((c) => c.status === "fail") || [];
+    for (const fail of cfFails.slice(0, 2)) {
+      console.log(
+        chalk.dim(`    Cloudflare: ${fail.id}`) +
+          chalk.dim(` — see isitagentready.com for fix`),
+      );
     }
-    console.log(
-      chalk.dim(
-        `\n  Run ${chalk.bold("npx aeo-ready scan --fix")} to auto-fix what we can.`,
-      ),
-    );
-    console.log(
-      chalk.dim(
-        "  Open the dashboard for step-by-step guides on everything else.\n",
-      ),
-    );
-  }
-}
-
-function printScorecard(name, scorecard) {
-  const pct = Math.round((scorecard.score / scorecard.maxScore) * 100);
-  console.log(
-    chalk.bold(`  ${name}`) +
-      chalk.dim(` ${scorecard.score}/${scorecard.maxScore} (${pct}%)`),
-  );
 
-  for (const [catName, cat] of Object.entries(scorecard.categories)) {
-    const label = formatCategoryName(catName);
-    const catPct = Math.round((cat.score / cat.maxScore) * 100);
-    const icon =
-      catPct >= 80
-        ? chalk.green("✓")
-        : catPct >= 40
-          ? chalk.yellow("◑")
-          : chalk.red("✗");
-    console.log(
-      `  ${icon} ${label.padEnd(28)} ${bar(cat.score, cat.maxScore, 20)} ${chalk.dim(`${cat.score}/${cat.maxScore} (${catPct}%)`)}`,
-    );
-
-    for (const check of cat.checks) {
-      if (check.passed) {
-        console.log(
-          chalk.green(`      +`) +
-            chalk.dim(` ${check.name} [${check.points}]`),
-        );
-      } else {
-        console.log(
-          chalk.red(`      -`) +
-            ` ${check.name} ` +
-            chalk.dim(`[${check.points || 0}/${check.maxPoints}]`),
-        );
-        if (check.fix) {
-          console.log(chalk.dim(`        ${check.fix}`));
-        }
-      }
+    const fernFails =
+      benchmarks.fern?.checks?.filter(
+        (c) => c.status === "fail" || c.status === "warn",
+      ) || [];
+    if (fernFails.length > 0) {
+      console.log(
+        chalk.dim(`    Fern: ${fernFails.length} issues`) +
+          chalk.dim(` — run npx afdocs ${result.url}`),
+      );
     }
-  }
-  console.log("");
-}
-
-function bar(value, max, width) {
-  const filled = max > 0 ? Math.round((value / max) * width) : 0;
-  const empty = width - filled;
-  const pct = max > 0 ? Math.round((value / max) * 100) : 0;
-  const color = pct >= 80 ? chalk.green : pct >= 50 ? chalk.yellow : chalk.red;
-  return color("█".repeat(filled)) + chalk.dim("░".repeat(empty));
-}
 
-function formatCategoryName(camelCase) {
-  return camelCase
-    .replace(/([A-Z])/g, " $1")
-    .replace(/^./, (c) => c.toUpperCase())
-    .trim();
+    console.log(chalk.dim("\n  Fix, then re-scan to track improvement.\n"));
+  }
 }
 
 function openInBrowser(filePath) {

package/src/checks/agent-readiness/actionable.js

@@ -1,165 +0,0 @@
-export async function runActionableChecks(context) {
-  const checks = [
-    checkContact(context),
-    checkPricing(context),
-    checkApiEndpoint(context),
-    checkSdkManifest(context),
-  ];
-
-  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
-  return { score, maxScore: 10, checks };
-}
-
-function checkContact(context) {
-  const html = context.html || "";
-  const allContent = getAllContent(context);
-
-  const hasEmail = /[\w.+-]+@[\w-]+\.[\w.]+/.test(allContent);
-  const hasCalLink = /cal\.com|calendly\.com|hubspot\.com\/meetings/.test(
-    allContent,
-  );
-  const hasStructuredContact =
-    allContent.includes("ContactPoint") || allContent.includes('"email"');
-
-  let points = 0;
-  if (hasEmail) points += 1;
-  if (hasCalLink) points += 1;
-  if (hasStructuredContact) points += 1;
-
-  if (points === 3) return pass("Machine-readable contact", 3);
-  if (points > 0) {
-    const missing = [];
-    if (!hasEmail) missing.push("email");
-    if (!hasCalLink) missing.push("booking link");
-    if (!hasStructuredContact) missing.push("structured ContactPoint");
-    return partial(
-      "Machine-readable contact",
-      points,
-      3,
-      `Add: ${missing.join(", ")}.`,
-    );
-  }
-  return fail(
-    "Machine-readable contact",
-    3,
-    "No machine-readable contact info. Add email, cal.com link, or ContactPoint schema.",
-  );
-}
-
-function checkPricing(context) {
-  if (context.siteType === "personal" || context.siteType === "content") {
-    return {
-      name: "Programmatic pricing",
-      passed: true,
-      points: 3,
-      maxPoints: 3,
-      note: "N/A for site type",
-    };
-  }
-
-  const allContent = getAllContent(context);
-  const files = context.files || [];
-
-  const hasPricingJson = files.some((f) => f.includes("pricing.json"));
-  const hasPriceSchema =
-    allContent.includes("PriceSpecification") || allContent.includes("offers");
-  const hasPricingPage =
-    allContent.includes("/pricing") || allContent.includes("pricing");
-
-  if (hasPricingJson || hasPriceSchema) return pass("Programmatic pricing", 3);
-  if (hasPricingPage)
-    return partial(
-      "Programmatic pricing",
-      1,
-      3,
-      "Pricing page exists but not in structured format. Add schema.org PriceSpecification or pricing.json.",
-    );
-  return fail(
-    "Programmatic pricing",
-    3,
-    "No programmatic pricing. Agents comparing you to competitors need structured plan data.",
-  );
-}
-
-function checkApiEndpoint(context) {
-  if (context.siteType === "personal") {
-    return {
-      name: "API endpoint",
-      passed: true,
-      points: 2,
-      maxPoints: 2,
-      note: "N/A for site type",
-    };
-  }
-
-  const allContent = getAllContent(context);
-  const hasApiRef = /\/api\/|\/v[12]\/|api-key|apikey/i.test(allContent);
-  const hasOpenApi =
-    context.files?.some((f) => f.includes("openapi")) ||
-    context.pages?.openapi?.status === 200;
-
-  if (hasApiRef && hasOpenApi) return pass("API endpoint", 2);
-  if (hasApiRef)
-    return partial(
-      "API endpoint",
-      1,
-      2,
-      "API references found but no formal spec. Add OpenAPI spec.",
-    );
-  return fail("API endpoint", 2, "No API endpoint detected.");
-}
-
-function checkSdkManifest(context) {
-  if (context.siteType === "personal" || context.siteType === "content") {
-    return {
-      name: "SDK / integration manifest",
-      passed: true,
-      points: 2,
-      maxPoints: 2,
-      note: "N/A for site type",
-    };
-  }
-
-  const allContent = getAllContent(context);
-  const hasSdk = /npm install|pip install|go get|cargo add|maven|gradle/i.test(
-    allContent,
-  );
-  const hasIntegrations = /integrat|connect|plugin|extension|mcp/i.test(
-    allContent,
-  );
-
-  if (hasSdk) return pass("SDK / integration manifest", 2);
-  if (hasIntegrations)
-    return partial(
-      "SDK / integration manifest",
-      1,
-      2,
-      "Integration mentions found but no install commands or SDK manifest.",
-    );
-  return fail(
-    "SDK / integration manifest",
-    2,
-    "No SDK or integration manifest detected.",
-  );
-}
-
-function getAllContent(context) {
-  if (context.mode === "url") {
-    return Object.values(context.pages || {})
-      .map((p) => p?.text || "")
-      .join("\n");
-  }
-  return Object.values(context.fileContents || {}).join("\n");
-}
-
-function pass(name, points) {
-  return { name, passed: true, points, maxPoints: points };
-}
-
-function partial(name, points, maxPoints, fix) {
-  return { name, passed: false, points, maxPoints, fix };
-}
-
-function fail(name, maxPoints, fix) {
-  return { name, passed: false, points: 0, maxPoints, fix };
-}