aeo-ready 1.1.0 → 1.2.0

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 };
-}

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

@@ -1,209 +0,0 @@
-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

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