aeo-ready 1.1.0 → 1.2.0

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

@@ -1,231 +0,0 @@
-import { estimateTokens } from "../../utils/tokens.js";
-
-const AI_CRAWLERS = [
-  "GPTBot",
-  "OAI-SearchBot",
-  "ClaudeBot",
-  "Claude-User",
-  "Claude-SearchBot",
-  "Google-Extended",
-  "PerplexityBot",
-  "Meta-ExternalAgent",
-  "CCBot",
-];
-
-export async function runDiscoveryChecks(context) {
-  const checks = [
-    checkLlmsTxt(context),
-    checkRobotsTxt(context),
-    checkSitemap(context),
-    checkAiMetaTags(context),
-  ];
-
-  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
-  return { score, maxScore: 12, checks };
-}
-
-function checkLlmsTxt(context) {
-  const content = getContent(context, "llms.txt", "/llms.txt");
-  if (!content) {
-    return fail(
-      "llms.txt",
-      4,
-      "No llms.txt found. Create one describing what your site does for AI agents.",
-    );
-  }
-
-  const tokens = estimateTokens(content);
-  if (tokens > 5000) {
-    return partial(
-      "llms.txt",
-      2,
-      4,
-      `llms.txt exists but is ${tokens} tokens (budget: <5000).`,
-    );
-  }
-
-  const hasUsefulContent =
-    content.length > 100 && !content.toLowerCase().includes("lorem");
-  if (!hasUsefulContent) {
-    return partial(
-      "llms.txt",
-      1,
-      4,
-      "llms.txt exists but has minimal/placeholder content.",
-    );
-  }
-
-  const frontLoaded = checkFrontLoading(content);
-  return frontLoaded
-    ? pass("llms.txt", 4)
-    : partial(
-        "llms.txt",
-        3,
-        4,
-        "llms.txt exists but doesn't front-load what/why/how in first 500 tokens.",
-      );
-}
-
-function checkRobotsTxt(context) {
-  const content = getContent(context, "robots.txt", "/robots.txt");
-  if (!content) {
-    return fail(
-      "robots.txt AI crawlers",
-      3,
-      "No robots.txt found. Add one with explicit AI crawler rules.",
-    );
-  }
-
-  const allowed = AI_CRAWLERS.filter(
-    (bot) => content.includes(bot) && hasAllow(content, bot),
-  );
-  const blocked = AI_CRAWLERS.filter(
-    (bot) => content.includes(bot) && hasDisallow(content, bot),
-  );
-
-  if (allowed.length >= 5) {
-    return pass("robots.txt AI crawlers", 3);
-  }
-  if (blocked.length > 3) {
-    return fail(
-      "robots.txt AI crawlers",
-      3,
-      `Blocks ${blocked.length} AI crawlers. Consider allowing for discoverability.`,
-    );
-  }
-  if (allowed.length > 0) {
-    return partial(
-      "robots.txt AI crawlers",
-      1,
-      3,
-      `Only ${allowed.length}/9 AI crawlers explicitly allowed.`,
-    );
-  }
-  return partial(
-    "robots.txt AI crawlers",
-    1,
-    3,
-    "robots.txt exists but doesn't mention AI crawlers. Add explicit Allow rules.",
-  );
-}
-
-function checkSitemap(context) {
-  const content = getContent(context, "sitemap.xml", "/sitemap.xml");
-  if (!content) {
-    return fail("sitemap.xml", 2, "No sitemap.xml found.");
-  }
-  const hasUrls = content.includes("<url>") || content.includes("<loc>");
-  return hasUrls
-    ? pass("sitemap.xml", 2)
-    : partial(
-        "sitemap.xml",
-        1,
-        2,
-        "sitemap.xml exists but has no URL entries.",
-      );
-}
-
-function checkAiMetaTags(context) {
-  const html = context.html || "";
-  if (!html) {
-    return fail(
-      "AI-friendly meta tags",
-      3,
-      "No HTML available to check meta tags.",
-    );
-  }
-
-  let points = 0;
-  if (html.includes("og:title") || html.includes("og:description")) points += 1;
-  if (
-    html.includes('meta name="description"') ||
-    html.includes("meta name='description'")
-  )
-    points += 1;
-  if (html.includes("application/ld+json")) points += 1;
-
-  if (points === 3) return pass("AI-friendly meta tags", 3);
-  if (points > 0)
-    return partial(
-      "AI-friendly meta tags",
-      points,
-      3,
-      "Some meta tags present but incomplete (need og:, description, JSON-LD).",
-    );
-  return fail(
-    "AI-friendly meta tags",
-    3,
-    "No AI-friendly meta tags (og:, description, JSON-LD) found.",
-  );
-}
-
-const PAGE_KEY_MAP = {
-  "llms.txt": "llmsTxt",
-  "robots.txt": "robotsTxt",
-  "sitemap.xml": "sitemap",
-  "agents.json": "agentJson",
-  "openapi.json": "openapi",
-  "openapi.yaml": "openapi",
-};
-
-function getContent(context, filename) {
-  if (context.mode === "url") {
-    const key = PAGE_KEY_MAP[filename];
-    const page = key ? context.pages[key] : null;
-    return page && page.status === 200 ? page.text : null;
-  }
-  const match = context.files.find(
-    (f) =>
-      f === filename ||
-      f.endsWith(`/${filename}`) ||
-      f === `public/${filename}`,
-  );
-  return match ? context.fileContents[match] : null;
-}
-
-function toCamelCase(filename) {
-  const name = filename.replace(/\.[^.]+$/, "");
-  return name.replace(/[-_.](.)/g, (_, c) => c.toUpperCase());
-}
-
-function hasAllow(robotsTxt, bot) {
-  const section = extractBotSection(robotsTxt, bot);
-  return (
-    section &&
-    /Allow:\s*\//.test(section) &&
-    !/Disallow:\s*\/\s*$/m.test(section)
-  );
-}
-
-function hasDisallow(robotsTxt, bot) {
-  const section = extractBotSection(robotsTxt, bot);
-  return section && /Disallow:\s*\/\s*$/m.test(section);
-}
-
-function extractBotSection(robotsTxt, bot) {
-  const regex = new RegExp(
-    `User-agent:\\s*${bot}[\\s\\S]*?(?=User-agent:|$)`,
-    "i",
-  );
-  const match = robotsTxt.match(regex);
-  return match ? match[0] : null;
-}
-
-function checkFrontLoading(text) {
-  const first500Tokens = text.slice(0, 2000);
-  const hasWhat = /what|does|is/i.test(first500Tokens);
-  const hasHow = /how|get started|install|use/i.test(first500Tokens);
-  return hasWhat && hasHow;
-}
-
-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 };
-}

package/src/checks/ai-visibility/authority.js

@@ -1,195 +0,0 @@
-export async function runAuthorityChecks(context) {
-  const checks = [
-    checkEeat(context),
-    checkEntityOptimization(context),
-    checkExternalValidation(context),
-  ];
-
-  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
-  return { score, maxScore: 13, checks };
-}
-
-function checkEeat(context) {
-  const allContent = getAllContent(context);
-  const html = context.html || "";
-
-  let points = 0;
-  const signals = [];
-
-  const hasAuthorBio =
-    /author|written by|by [A-Z]/i.test(allContent) &&
-    (/bio|about the author|expertise|experience/i.test(allContent) ||
-      allContent.includes("Person"));
-  if (hasAuthorBio) {
-    points += 1;
-    signals.push("author bio");
-  }
-
-  const hasCredentials =
-    /credential|certified|years of experience|expert|specialist|phd|mba/i.test(
-      allContent,
-    );
-  if (hasCredentials) {
-    points += 1;
-    signals.push("credentials");
-  }
-
-  const hasExperience =
-    /built|shipped|worked on|founded|created|contributed to/i.test(allContent);
-  if (hasExperience) {
-    points += 1;
-    signals.push("experience signals");
-  }
-
-  const hasPersonSchema =
-    allContent.includes('"Person"') || allContent.includes("'Person'");
-  if (hasPersonSchema) {
-    points += 1;
-    signals.push("Person schema");
-  }
-
-  if (points === 4) return pass("E-E-A-T signals", 4);
-  if (points > 0) {
-    const missing = [];
-    if (!hasAuthorBio) missing.push("author bios");
-    if (!hasCredentials) missing.push("credentials");
-    if (!hasExperience) missing.push("first-hand experience");
-    if (!hasPersonSchema) missing.push("Person schema");
-    return partial(
-      "E-E-A-T signals",
-      points,
-      4,
-      `Has: ${signals.join(", ")}. Missing: ${missing.join(", ")}.`,
-    );
-  }
-  return fail(
-    "E-E-A-T signals",
-    4,
-    "No E-E-A-T signals (author bios, credentials, experience markers, Person schema). AI prioritizes authoritative sources.",
-  );
-}
-
-function checkEntityOptimization(context) {
-  const allContent = getAllContent(context);
-
-  let points = 0;
-  const signals = [];
-
-  const hasSameAs = allContent.includes("sameAs");
-  if (hasSameAs) {
-    points += 1;
-    signals.push("sameAs links");
-  }
-
-  const hasConsistentNaming = checkNameConsistency(allContent, context);
-  if (hasConsistentNaming) {
-    points += 1;
-    signals.push("consistent naming");
-  }
-
-  const hasIdentifiers = /github\.com|linkedin\.com|twitter\.com|x\.com/i.test(
-    allContent,
-  );
-  if (hasIdentifiers) {
-    points += 2;
-    signals.push("cross-platform identifiers");
-  }
-
-  if (points >= 3) return pass("Entity optimization", 3);
-  if (points > 0) {
-    return partial(
-      "Entity optimization",
-      Math.min(points, 2),
-      3,
-      `Entity signals: ${signals.join(", ")}. Add sameAs links and consistent naming across platforms.`,
-    );
-  }
-  return fail(
-    "Entity optimization",
-    3,
-    "No entity optimization. Add sameAs links, consistent naming, and cross-platform profile links for AI entity resolution.",
-  );
-}
-
-function checkExternalValidation(context) {
-  const allContent = getAllContent(context);
-
-  let points = 0;
-
-  const hasExternalLinks =
-    /https?:\/\/(?!.*(?:localhost|127\.0\.0|example\.com))/i.test(allContent);
-  if (hasExternalLinks) points += 1;
-
-  const hasCitations =
-    /\[\d+\]|source:|reference:|according to|research shows/i.test(allContent);
-  if (hasCitations) points += 1;
-
-  const hasDataClaims =
-    /\d+%|\d+x|\$[\d,]+|increased by|reduced by|improved/i.test(allContent);
-  if (hasDataClaims) points += 1;
-
-  if (points === 3) return pass("External validation & references", 3);
-  if (points > 0) {
-    const missing = [];
-    if (!hasExternalLinks) missing.push("external source links");
-    if (!hasCitations) missing.push("cited references");
-    if (!hasDataClaims) missing.push("quantified claims");
-    return partial(
-      "External validation & references",
-      points,
-      3,
-      `Add: ${missing.join(", ")}. AI trusts content that cites sources.`,
-    );
-  }
-  return fail(
-    "External validation & references",
-    3,
-    "No external validation — no cited sources, references, or quantified claims. AI weighs evidence-backed content higher.",
-  );
-}
-
-function checkNameConsistency(content, context) {
-  if (context.mode === "url" && context.url) {
-    try {
-      const hostname = new URL(context.url).hostname
-        .replace("www.", "")
-        .split(".")[0];
-      const mentions =
-        content.toLowerCase().split(hostname.toLowerCase()).length - 1;
-      return mentions >= 3;
-    } catch {
-      return false;
-    }
-  }
-  const pkg = context.fileContents?.["package.json"];
-  if (pkg) {
-    try {
-      const name = JSON.parse(pkg).name;
-      return name && content.split(name).length > 3;
-    } catch {
-      return false;
-    }
-  }
-  return false;
-}
-
-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 };
-}

package/src/checks/ai-visibility/citation-readiness.js

@@ -1,228 +0,0 @@
-export async function runCitationReadinessChecks(context) {
-  const checks = [
-    checkDirectAnswerFormat(context),
-    checkQuestionHeadings(context),
-    checkCitationStructure(context),
-    checkDefinitiveStatements(context),
-  ];
-
-  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
-  return { score, maxScore: 15, checks };
-}
-
-function checkDirectAnswerFormat(context) {
-  const pages = getPageContents(context);
-  if (pages.length === 0) {
-    return fail("Direct answer formatting", 4, "No content pages to analyze.");
-  }
-
-  let directAnswerCount = 0;
-  for (const page of pages.slice(0, 10)) {
-    const paragraphs = extractParagraphs(page.content);
-    const firstSubstantial = paragraphs.find((p) => p.length > 80);
-    if (firstSubstantial) {
-      const wordCount = firstSubstantial.split(/\s+/).length;
-      if (wordCount >= 30 && wordCount <= 80) directAnswerCount++;
-    }
-  }
-
-  const ratio = directAnswerCount / Math.min(pages.length, 10);
-  if (ratio >= 0.6) return pass("Direct answer formatting", 4);
-  if (ratio >= 0.3)
-    return partial(
-      "Direct answer formatting",
-      2,
-      4,
-      `Only ${Math.round(ratio * 100)}% of pages lead with a 40-60 word summary. AI systems extract these as citations.`,
-    );
-  return partial(
-    "Direct answer formatting",
-    1,
-    4,
-    "Most pages don't lead with a concise summary (40-60 words). This is what AI systems cite.",
-  );
-}
-
-function checkQuestionHeadings(context) {
-  const content = getAllTextContent(context);
-  if (!content) {
-    return fail("Question-based headings", 4, "No content to analyze.");
-  }
-
-  const headings = extractHeadings(content);
-  if (headings.length === 0) {
-    return fail("Question-based headings", 4, "No headings found in content.");
-  }
-
-  const questionHeadings = headings.filter(
-    (h) =>
-      h.endsWith("?") ||
-      /^(what|how|why|when|where|who|which|can|does|is|are|do)\b/i.test(h),
-  );
-
-  const ratio = questionHeadings.length / headings.length;
-  if (ratio >= 0.3) return pass("Question-based headings", 4);
-  if (ratio >= 0.1)
-    return partial(
-      "Question-based headings",
-      2,
-      4,
-      `${questionHeadings.length}/${headings.length} headings are question-based. Aim for 30%+ — these match how users query AI.`,
-    );
-  if (questionHeadings.length > 0)
-    return partial(
-      "Question-based headings",
-      1,
-      4,
-      "Very few question-based headings. Rephrase key H2/H3s as questions users would ask AI.",
-    );
-  return fail(
-    "Question-based headings",
-    4,
-    'No question-based headings. AI systems match user queries to headings — use "What is X?" / "How to Y?" format.',
-  );
-}
-
-function checkCitationStructure(context) {
-  const pages = getPageContents(context);
-  if (pages.length === 0) {
-    return fail(
-      "Citation-friendly structure",
-      4,
-      "No content pages to analyze.",
-    );
-  }
-
-  let score = 0;
-  let issues = [];
-
-  const avgParaLength = getAverageParagraphLength(pages);
-  if (avgParaLength <= 100) {
-    score += 2;
-  } else if (avgParaLength <= 150) {
-    score += 1;
-    issues.push("paragraphs slightly long for citation extraction");
-  } else {
-    issues.push("paragraphs too long — AI prefers short, citable blocks");
-  }
-
-  const hasLists = pages.some(
-    (p) =>
-      p.content.includes("- ") ||
-      p.content.includes("* ") ||
-      /<[ou]l/i.test(p.content),
-  );
-  if (hasLists) score += 1;
-  else issues.push("no lists — AI extracts bulleted info easily");
-
-  const hasTables = pages.some(
-    (p) => p.content.includes("|") || /<table/i.test(p.content),
-  );
-  if (hasTables) score += 1;
-  else issues.push("no tables — structured comparisons get cited");
-
-  if (score === 4) return pass("Citation-friendly structure", 4);
-  return partial(
-    "Citation-friendly structure",
-    score,
-    4,
-    issues.join("; ") + ".",
-  );
-}
-
-function checkDefinitiveStatements(context) {
-  const content = getAllTextContent(context);
-  if (!content) {
-    return fail("Definitive statements", 3, "No content to analyze.");
-  }
-
-  const sentences = content.split(/[.!]\s+/).filter((s) => s.length > 20);
-  const definitive = sentences.filter(
-    (s) =>
-      /\b(is|are|was|means|defined as|refers to|consists of)\b/i.test(s) &&
-      !/\b(might|maybe|perhaps|possibly|could be|generally)\b/i.test(s),
-  );
-
-  const ratio = sentences.length > 0 ? definitive.length / sentences.length : 0;
-  if (ratio >= 0.2) return pass("Definitive statements", 3);
-  if (ratio >= 0.1)
-    return partial(
-      "Definitive statements",
-      2,
-      3,
-      "Some definitive statements but too much hedging. AI cites confident claims over uncertain ones.",
-    );
-  return partial(
-    "Definitive statements",
-    1,
-    3,
-    "Content uses weak/uncertain language. Make clear, definitive claims that AI can cite with confidence.",
-  );
-}
-
-function getPageContents(context) {
-  if (context.mode === "url") {
-    return context.html ? [{ name: "homepage", content: context.html }] : [];
-  }
-  return context.files
-    .filter((f) => f.endsWith(".md") || f.endsWith(".html"))
-    .map((f) => ({ name: f, content: context.fileContents[f] || "" }))
-    .filter((p) => p.content.length > 0);
-}
-
-function getAllTextContent(context) {
-  if (context.mode === "url") return context.html || "";
-  return context.files
-    .filter(
-      (f) => f.endsWith(".md") || f.endsWith(".html") || f.endsWith(".txt"),
-    )
-    .map((f) => context.fileContents[f] || "")
-    .join("\n");
-}
-
-function extractParagraphs(content) {
-  if (content.includes("<p")) {
-    return [...content.matchAll(/<p[^>]*>([\s\S]*?)<\/p>/gi)].map((m) =>
-      stripTags(m[1]).trim(),
-    );
-  }
-  return content
-    .split(/\n\n+/)
-    .map((p) => p.trim())
-    .filter((p) => p.length > 0 && !p.startsWith("#"));
-}
-
-function extractHeadings(content) {
-  const md = [...content.matchAll(/^#{1,6}\s+(.+)$/gm)].map((m) => m[1]);
-  const html = [...content.matchAll(/<h[1-6][^>]*>([^<]+)/gi)].map((m) => m[1]);
-  return md.length > html.length ? md : html;
-}
-
-function getAverageParagraphLength(pages) {
-  let total = 0;
-  let count = 0;
-  for (const page of pages) {
-    const paras = extractParagraphs(page.content).filter((p) => p.length > 20);
-    for (const p of paras) {
-      total += p.split(/\s+/).length;
-      count++;
-    }
-  }
-  return count > 0 ? total / count : 0;
-}
-
-function stripTags(html) {
-  return html.replace(/<[^>]+>/g, "");
-}
-
-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 };
-}