aeo-ready 1.0.0

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

@@ -0,0 +1,209 @@
+export async function runCapabilityChecks(context) {
+  const checks = [
+    checkAgentInstructions(context),
+    checkAgentManifest(context),
+    checkOpenApiSpec(context),
+    checkContentNegotiation(context),
+  ];
+
+  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
+  return { score, maxScore: 13, checks };
+}
+
+function checkAgentInstructions(context) {
+  const names = ["AGENTS.md", "CLAUDE.md", "agents.md", "claude.md"];
+  const skillFiles = ["skill.md", "skills/"];
+
+  if (context.mode === "url") {
+    const html = context.html || "";
+    const hasAgentFile = names.some((n) => html.includes(n));
+    return hasAgentFile
+      ? partial(
+          "AGENTS.md / CLAUDE.md",
+          2,
+          4,
+          "Referenced in HTML but not directly accessible at known path.",
+        )
+      : fail(
+          "AGENTS.md / CLAUDE.md",
+          4,
+          "No agent instruction file (AGENTS.md, CLAUDE.md) detected.",
+        );
+  }
+
+  const found = context.files.find((f) => {
+    const base = f.split("/").pop();
+    return names.includes(base) || skillFiles.some((s) => f.includes(s));
+  });
+
+  if (!found) {
+    return fail(
+      "AGENTS.md / CLAUDE.md",
+      4,
+      "No agent instruction file found. Add AGENTS.md or CLAUDE.md to repo root.",
+    );
+  }
+
+  const content = context.fileContents[found] || "";
+  const hasStructure = content.includes("#") && content.length > 200;
+  const hasConstraints = /constraint|limit|rate|require/i.test(content);
+  const hasCapabilities = /capabilit|can do|feature|endpoint/i.test(content);
+
+  let points = 2;
+  if (hasStructure && hasCapabilities) points = 3;
+  if (hasStructure && hasCapabilities && hasConstraints) points = 4;
+
+  if (points === 4) return pass("AGENTS.md / CLAUDE.md", 4);
+  const missing = [];
+  if (!hasCapabilities) missing.push("capabilities");
+  if (!hasConstraints) missing.push("constraints/limits");
+  return partial(
+    "AGENTS.md / CLAUDE.md",
+    points,
+    4,
+    `Agent file exists but missing: ${missing.join(", ")}.`,
+  );
+}
+
+function checkAgentManifest(context) {
+  const content = getContent(context, "agents.json", "/.well-known/agent.json");
+
+  if (!content) {
+    return fail(
+      "agents.json manifest",
+      3,
+      "No agents.json or .well-known/agent.json found.",
+    );
+  }
+
+  try {
+    const manifest = JSON.parse(content);
+    const hasName = !!manifest.name;
+    const hasCapabilities =
+      Array.isArray(manifest.capabilities) && manifest.capabilities.length > 0;
+    const hasInterfaces = !!manifest.interfaces;
+
+    if (hasName && hasCapabilities && hasInterfaces)
+      return pass("agents.json manifest", 3);
+    const missing = [];
+    if (!hasName) missing.push("name");
+    if (!hasCapabilities) missing.push("capabilities");
+    if (!hasInterfaces) missing.push("interfaces");
+    return partial(
+      "agents.json manifest",
+      1,
+      3,
+      `agents.json exists but missing: ${missing.join(", ")}.`,
+    );
+  } catch {
+    return partial(
+      "agents.json manifest",
+      1,
+      3,
+      "agents.json exists but is not valid JSON.",
+    );
+  }
+}
+
+function checkOpenApiSpec(context) {
+  const jsonContent = getContent(context, "openapi.json", "/openapi.json");
+  const yamlContent = getContent(context, "openapi.yaml", "/openapi.yaml");
+  const content = jsonContent || yamlContent;
+
+  if (!content) {
+    if (context.siteType === "content" || context.siteType === "personal") {
+      return {
+        name: "OpenAPI spec",
+        passed: true,
+        points: 3,
+        maxPoints: 3,
+        note: "N/A for site type",
+      };
+    }
+    return fail(
+      "OpenAPI spec",
+      3,
+      "No OpenAPI spec found. Add openapi.json or openapi.yaml.",
+    );
+  }
+
+  const hasEndpoints = content.includes("paths") || content.includes("/api");
+  const hasVersion = content.includes("openapi") || content.includes("swagger");
+
+  if (hasEndpoints && hasVersion) return pass("OpenAPI spec", 3);
+  return partial(
+    "OpenAPI spec",
+    2,
+    3,
+    "OpenAPI spec exists but may be incomplete.",
+  );
+}
+
+function checkContentNegotiation(context) {
+  if (context.mode === "url") {
+    const headers = context.pages.home?.headers || {};
+    const acceptsMarkdown =
+      headers["content-type"]?.includes("markdown") ||
+      headers["vary"]?.includes("Accept");
+    return acceptsMarkdown
+      ? pass("Content negotiation", 3)
+      : fail(
+          "Content negotiation",
+          3,
+          "No content negotiation detected. Serve markdown when Accept: text/markdown is requested.",
+        );
+  }
+
+  const hasMiddleware = context.files.some(
+    (f) => f.includes("middleware") || f.includes("negotiat"),
+  );
+  if (hasMiddleware)
+    return partial(
+      "Content negotiation",
+      2,
+      3,
+      "Middleware detected — verify Accept: text/markdown is handled.",
+    );
+  return fail(
+    "Content negotiation",
+    3,
+    "No content negotiation setup. Consider serving markdown for Accept: text/markdown requests.",
+  );
+}
+
+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 === `.well-known/${filename}` ||
+      f === `public/.well-known/${filename}`,
+  );
+  return match ? context.fileContents[match] : null;
+}
+
+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/agent-readiness/content-structure.js

@@ -0,0 +1,242 @@
+import { estimateTokens, TOKEN_BUDGETS } from "../../utils/tokens.js";
+
+export async function runContentStructureChecks(context) {
+  const checks = [
+    checkMarkdownAvailability(context),
+    checkHeadingHierarchy(context),
+    checkTokenBudgets(context),
+    checkFrontLoading(context),
+    checkCopyForAi(context),
+  ];
+
+  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
+  return { score, maxScore: 15, checks };
+}
+
+function checkMarkdownAvailability(context) {
+  if (context.mode === "url") {
+    const html = context.html || "";
+    const hasMarkdownLink =
+      html.includes(".md") || html.includes("text/markdown");
+    return hasMarkdownLink
+      ? pass("Markdown content available", 3)
+      : fail(
+          "Markdown content available",
+          3,
+          "No markdown versions of content detected. Serve .md files or support Accept: text/markdown.",
+        );
+  }
+
+  const mdFiles = context.files.filter((f) => f.endsWith(".md"));
+  if (mdFiles.length === 0) {
+    return fail(
+      "Markdown content available",
+      3,
+      "No markdown files found in project.",
+    );
+  }
+  if (mdFiles.length >= 3) return pass("Markdown content available", 3);
+  return partial(
+    "Markdown content available",
+    2,
+    3,
+    `Only ${mdFiles.length} markdown files. More content should be in .md format.`,
+  );
+}
+
+function checkHeadingHierarchy(context) {
+  const content = getAllTextContent(context);
+  if (!content) {
+    return fail(
+      "Heading hierarchy",
+      3,
+      "No content available to analyze headings.",
+    );
+  }
+
+  const headings = extractHeadings(content);
+  if (headings.length === 0) {
+    return fail("Heading hierarchy", 3, "No headings found in content.");
+  }
+
+  const hasH1 = headings.some((h) => h.level === 1);
+  const hierarchyValid = checkHierarchyOrder(headings);
+  const noSkips = !hasLevelSkips(headings);
+
+  let points = 0;
+  if (hasH1) points += 1;
+  if (hierarchyValid) points += 1;
+  if (noSkips) points += 1;
+
+  if (points === 3) return pass("Heading hierarchy", 3);
+  const issues = [];
+  if (!hasH1) issues.push("no H1");
+  if (!hierarchyValid) issues.push("inconsistent hierarchy");
+  if (!noSkips) issues.push("skipped heading levels");
+  return partial(
+    "Heading hierarchy",
+    points,
+    3,
+    `Heading issues: ${issues.join(", ")}.`,
+  );
+}
+
+function checkTokenBudgets(context) {
+  const content = getAllTextContent(context);
+  if (!content) {
+    return fail(
+      "Token budget compliance",
+      4,
+      "No content to measure token counts.",
+    );
+  }
+
+  const pages = getPageContents(context);
+  if (pages.length === 0) {
+    return partial(
+      "Token budget compliance",
+      2,
+      4,
+      "Could not identify individual pages to check budgets.",
+    );
+  }
+
+  const overBudget = pages.filter((p) => estimateTokens(p.content) > 25000);
+  const avgTokens =
+    pages.reduce((sum, p) => sum + estimateTokens(p.content), 0) / pages.length;
+
+  if (overBudget.length === 0 && avgTokens < 15000)
+    return pass("Token budget compliance", 4);
+  if (overBudget.length === 0)
+    return partial(
+      "Token budget compliance",
+      3,
+      4,
+      `Average page is ${Math.round(avgTokens)} tokens. Under 15K is ideal.`,
+    );
+  return partial(
+    "Token budget compliance",
+    1,
+    4,
+    `${overBudget.length} pages exceed 25K token budget.`,
+  );
+}
+
+function checkFrontLoading(context) {
+  const pages = getPageContents(context);
+  if (pages.length === 0) {
+    return fail(
+      "Front-loading (first 500 tokens)",
+      3,
+      "No pages to analyze for front-loading.",
+    );
+  }
+
+  let frontLoaded = 0;
+  for (const page of pages.slice(0, 10)) {
+    const first2000Chars = page.content.slice(0, 2000);
+    const hasWhat = /\b(what|is|does|provides?|offers?)\b/i.test(
+      first2000Chars,
+    );
+    const hasWhy = /\b(why|because|benefit|solves?|helps?)\b/i.test(
+      first2000Chars,
+    );
+    if (hasWhat && hasWhy) frontLoaded++;
+  }
+
+  const ratio = frontLoaded / Math.min(pages.length, 10);
+  if (ratio >= 0.8) return pass("Front-loading (first 500 tokens)", 3);
+  if (ratio >= 0.5)
+    return partial(
+      "Front-loading (first 500 tokens)",
+      2,
+      3,
+      `Only ${Math.round(ratio * 100)}% of pages front-load what/why in first 500 tokens.`,
+    );
+  return partial(
+    "Front-loading (first 500 tokens)",
+    1,
+    3,
+    `Most pages don\'t answer what/why/how in first 500 tokens. Lead with the point.`,
+  );
+}
+
+function checkCopyForAi(context) {
+  const html = context.html || "";
+  const files = context.files || [];
+
+  const hasCopyButton =
+    html.includes("copy") &&
+    (html.includes("markdown") || html.includes("clipboard"));
+  const hasMarkdownExport = files.some(
+    (f) => f.includes("export") && f.endsWith(".md"),
+  );
+
+  if (hasCopyButton) return pass("Copy-for-AI affordances", 2);
+  if (hasMarkdownExport)
+    return partial(
+      "Copy-for-AI affordances",
+      1,
+      2,
+      "Markdown export exists but no copy-as-markdown button detected.",
+    );
+  return fail(
+    "Copy-for-AI affordances",
+    2,
+    'No copy-for-AI affordances. Add a "Copy as Markdown" button on doc pages.',
+  );
+}
+
+function getAllTextContent(context) {
+  if (context.mode === "url") return context.html || "";
+  const textFiles = context.files.filter(
+    (f) => f.endsWith(".md") || f.endsWith(".html") || f.endsWith(".txt"),
+  );
+  return textFiles.map((f) => context.fileContents[f] || "").join("\n");
+}
+
+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 extractHeadings(content) {
+  const mdHeadings = [...content.matchAll(/^(#{1,6})\s+(.+)$/gm)].map((m) => ({
+    level: m[1].length,
+    text: m[2],
+  }));
+  const htmlHeadings = [...content.matchAll(/<h([1-6])[^>]*>([^<]+)/gi)].map(
+    (m) => ({ level: parseInt(m[1]), text: m[2] }),
+  );
+  return mdHeadings.length > htmlHeadings.length ? mdHeadings : htmlHeadings;
+}
+
+function checkHierarchyOrder(headings) {
+  if (headings.length < 2) return true;
+  const firstLevel = headings[0].level;
+  return headings.slice(1).every((h) => h.level >= firstLevel);
+}
+
+function hasLevelSkips(headings) {
+  for (let i = 1; i < headings.length; i++) {
+    if (headings[i].level - headings[i - 1].level > 1) return true;
+  }
+  return false;
+}
+
+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/agent-readiness/discovery.js

@@ -0,0 +1,231 @@
+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 };
+}