aeo-ready 1.0.0

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

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

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

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

@@ -0,0 +1,182 @@
+export async function runFreshnessChecks(context) {
+  const checks = [
+    checkModifiedDates(context),
+    checkPublicationCadence(context),
+    checkContentRecency(context),
+    checkEvergreenFlags(context),
+  ];
+
+  const score = checks.reduce((sum, c) => sum + (c.passed ? c.points : 0), 0);
+  return { score, maxScore: 10, checks };
+}
+
+function checkModifiedDates(context) {
+  const allContent = getAllContent(context);
+  const html = context.html || "";
+
+  const hasDateModified = /dateModified|lastmod|last.modified|updated/i.test(
+    allContent,
+  );
+  const hasDatePublished = /datePublished|pubdate|published/i.test(allContent);
+  const hasMetaDate = /article:modified_time|article:published_time/i.test(
+    html,
+  );
+
+  let points = 0;
+  if (hasDateModified || hasMetaDate) points += 2;
+  if (hasDatePublished) points += 1;
+
+  if (points === 3) return pass("Last modified dates", 3);
+  if (points > 0) {
+    const missing = [];
+    if (!hasDateModified && !hasMetaDate) missing.push("dateModified");
+    if (!hasDatePublished) missing.push("datePublished");
+    return partial(
+      "Last modified dates",
+      points,
+      3,
+      `Add ${missing.join(" and ")} to structured data. AI systems prioritize fresh content.`,
+    );
+  }
+  return fail(
+    "Last modified dates",
+    3,
+    "No date metadata found. Add dateModified and datePublished to structured data or meta tags.",
+  );
+}
+
+function checkPublicationCadence(context) {
+  const allContent = getAllContent(context);
+
+  const dates = extractDates(allContent);
+  if (dates.length < 2) {
+    return partial(
+      "Publication cadence",
+      1,
+      2,
+      "Not enough dated content to assess publication cadence.",
+    );
+  }
+
+  const sorted = dates.sort((a, b) => b - a);
+  const gaps = [];
+  for (let i = 0; i < Math.min(sorted.length - 1, 5); i++) {
+    gaps.push(sorted[i] - sorted[i + 1]);
+  }
+  const avgGapDays =
+    gaps.reduce((s, g) => s + g, 0) / gaps.length / (1000 * 60 * 60 * 24);
+
+  if (avgGapDays <= 30) return pass("Publication cadence", 2);
+  if (avgGapDays <= 90)
+    return partial(
+      "Publication cadence",
+      1,
+      2,
+      `Average ${Math.round(avgGapDays)} days between publications. Monthly or better signals active maintenance.`,
+    );
+  return fail(
+    "Publication cadence",
+    2,
+    `Infrequent updates (~${Math.round(avgGapDays)} day gaps). Regular publishing signals authority to AI systems.`,
+  );
+}
+
+function checkContentRecency(context) {
+  const allContent = getAllContent(context);
+  const dates = extractDates(allContent);
+
+  if (dates.length === 0) {
+    return fail("Content recency", 3, "No dates found to assess content age.");
+  }
+
+  const now = Date.now();
+  const oneYear = 365 * 24 * 60 * 60 * 1000;
+  const recentDates = dates.filter((d) => now - d < oneYear);
+  const ratio = recentDates.length / dates.length;
+
+  if (ratio >= 0.5) return pass("Content recency", 3);
+  if (ratio >= 0.2)
+    return partial(
+      "Content recency",
+      2,
+      3,
+      `Only ${Math.round(ratio * 100)}% of dated content is from the last 12 months.`,
+    );
+  return partial(
+    "Content recency",
+    1,
+    3,
+    "Most content appears older than 12 months. Update key pages or add new content.",
+  );
+}
+
+function checkEvergreenFlags(context) {
+  const allContent = getAllContent(context);
+
+  const hasEvergreen = /evergreen|timeless|guide|reference|documentation/i.test(
+    allContent,
+  );
+  const hasVersioning = /v\d|version \d|updated for \d{4}|as of \d{4}/i.test(
+    allContent,
+  );
+
+  if (hasEvergreen && hasVersioning)
+    return pass("Evergreen content flagged", 2);
+  if (hasEvergreen || hasVersioning)
+    return partial(
+      "Evergreen content flagged",
+      1,
+      2,
+      'Some content signals permanence. Add "Updated for 2026" or version markers to evergreen pieces.',
+    );
+  return fail(
+    "Evergreen content flagged",
+    2,
+    "No evergreen content markers. Flag reference content as timeless so AI doesn't deprioritize it for age.",
+  );
+}
+
+function extractDates(content) {
+  const patterns = [
+    /\d{4}-\d{2}-\d{2}/g,
+    /\d{4}\/\d{2}\/\d{2}/g,
+    /(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\w*\s+\d{1,2},?\s+\d{4}/gi,
+  ];
+
+  const dates = [];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const d = new Date(match[0]);
+      if (
+        !isNaN(d.getTime()) &&
+        d.getFullYear() >= 2015 &&
+        d.getFullYear() <= 2030
+      ) {
+        dates.push(d.getTime());
+      }
+    }
+  }
+  return [...new Set(dates)];
+}
+
+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 };
+}