aeorank 1.2.3 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # AEORank
 
-Score any website for AI engine visibility across 23 criteria. Pure HTTP + regex - zero API keys required.
+Score any website for AI engine visibility across 26 criteria. Pure HTTP + regex - zero API keys required.
 
 [![npm version](https://img.shields.io/npm/v/aeorank.svg)](https://www.npmjs.com/package/aeorank)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -33,13 +33,13 @@ import { audit } from 'aeorank';
 
 const result = await audit('example.com');
 console.log(result.overallScore);  // 0-100
-console.log(result.scorecard);     // 23 criteria with scores
+console.log(result.scorecard);     // 26 criteria with scores
 console.log(result.opportunities); // Prioritized improvements
 ```
 
 ## What It Checks
 
-AEORank evaluates 23 criteria across 4 categories that determine how AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) discover, parse, and cite your content:
+AEORank evaluates 26 criteria across 4 categories that determine how AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) discover, parse, and cite your content:
 
 | # | Criterion | Weight | Category |
 |---|-----------|--------|----------|
@@ -66,6 +66,9 @@ AEORank evaluates 23 criteria across 4 categories that determine how AI engines
 | 21 | Content Publishing Velocity | 3% | Content |
 | 22 | Schema Coverage & Depth | 3% | Structure |
 | 23 | Speakable Schema | 3% | Structure |
+| 24 | Query-Answer Alignment | 8% | Content |
+| 25 | Content Cannibalization | 5% | Content |
+| 26 | Visible Date Signal | 4% | Content |
 
 ## CLI Options
 

package/dist/cli.js

@@ -1392,6 +1392,209 @@ function checkSpeakableSchema(data) {
   }
   return { criterion: "speakable_schema", criterion_label: "Speakable Schema", score: Math.min(10, score), status: score >= 7 ? "pass" : score >= 4 ? "partial" : "fail", findings, fix_priority: score >= 7 ? "P3" : "P2" };
 }
+function extractQuestionHeadings(html) {
+  const hTags = (html.match(/<h[23][^>]*>([\s\S]*?)<\/h[23]>/gi) || []).map((h) => h.replace(/<[^>]*>/g, "").trim());
+  return hTags.filter((h) => h.includes("?") || /^(what|how|why|when|who|where|can|do|does|is|are|should)\s/i.test(h));
+}
+function checkQueryAnswerAlignment(data) {
+  const findings = [];
+  if (!data.homepage) {
+    findings.push({ severity: "critical", detail: "No homepage available for query-answer alignment analysis" });
+    return { criterion: "query_answer_alignment", criterion_label: "Query-Answer Alignment", score: 0, status: "fail", findings, fix_priority: "P1" };
+  }
+  const combinedHtml = getCombinedHtml(data);
+  const questionHeadings = extractQuestionHeadings(combinedHtml);
+  if (questionHeadings.length === 0) {
+    findings.push({ severity: "info", detail: "No question-format headings (H2/H3) found - scoring neutral", fix: 'Add question-based headings like "What is...?", "How does...?" to enable Q&A snippet extraction' });
+    return { criterion: "query_answer_alignment", criterion_label: "Query-Answer Alignment", score: 5, status: "partial", findings, fix_priority: "P2" };
+  }
+  let answered = 0;
+  for (const qHeading of questionHeadings) {
+    const escapedHeading = qHeading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(escapedHeading + "[\\s\\S]{0,200}?<\\/h[23]>([\\s\\S]{0,1500}?)(?=<h[1-6]|$)", "i");
+    const match = pattern.exec(combinedHtml);
+    if (match) {
+      const afterContent = match[1].replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+      if (afterContent.length >= 20) {
+        answered++;
+      }
+    }
+  }
+  const rate = Math.round(answered / questionHeadings.length * 100);
+  let score;
+  if (rate >= 80) {
+    score = 10;
+    findings.push({ severity: "info", detail: `${answered}/${questionHeadings.length} question headings (${rate}%) followed by direct answers - excellent alignment` });
+  } else if (rate >= 50) {
+    score = 7;
+    findings.push({ severity: "low", detail: `${answered}/${questionHeadings.length} question headings (${rate}%) have answers`, fix: "Add concise answer paragraphs after remaining unanswered question headings" });
+  } else if (rate > 0) {
+    score = 4;
+    findings.push({ severity: "medium", detail: `Only ${answered}/${questionHeadings.length} question headings (${rate}%) are followed by answers`, fix: "Ensure each question heading is immediately followed by a direct answer paragraph" });
+  } else {
+    score = 0;
+    findings.push({ severity: "high", detail: `${questionHeadings.length} question headings found but none have direct answers`, fix: "Add answer paragraphs (2-3 sentences) immediately after each question heading" });
+  }
+  return { criterion: "query_answer_alignment", criterion_label: "Query-Answer Alignment", score, status: score >= 7 ? "pass" : score >= 4 ? "partial" : "fail", findings, fix_priority: score >= 7 ? "P3" : "P1" };
+}
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "from",
+  "is",
+  "it",
+  "as",
+  "be",
+  "was",
+  "are",
+  "this",
+  "that",
+  "your",
+  "our",
+  "we",
+  "you",
+  "how",
+  "what",
+  "why"
+]);
+function extractPageTitle(html) {
+  const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+  const h1Match = html.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i);
+  const title = titleMatch?.[1]?.trim() || "";
+  const h1 = h1Match?.[1]?.replace(/<[^>]*>/g, "").trim() || "";
+  return (title + " " + h1).toLowerCase().trim();
+}
+function titleToWordSet(title) {
+  return new Set(
+    title.split(/\s+/).filter((w) => w.length > 1 && !STOP_WORDS.has(w))
+  );
+}
+function jaccardSimilarity(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersection = 0;
+  for (const word of a) {
+    if (b.has(word)) intersection++;
+  }
+  const union = a.size + b.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+function checkContentCannibalization(data) {
+  const findings = [];
+  if (!data.homepage) {
+    findings.push({ severity: "critical", detail: "No homepage available for cannibalization analysis" });
+    return { criterion: "content_cannibalization", criterion_label: "Content Cannibalization", score: 0, status: "fail", findings, fix_priority: "P1" };
+  }
+  const pages = [
+    { html: data.homepage.text, url: data.homepage.finalUrl || `https://${data.domain}/` }
+  ];
+  if (data.blogSample) {
+    for (const page of data.blogSample.slice(0, 5)) {
+      pages.push({ html: page.text, url: page.finalUrl || "" });
+    }
+  }
+  if (pages.length <= 1) {
+    findings.push({ severity: "info", detail: "Only homepage available - cannot assess content cannibalization", fix: "Add blog/content pages to enable cross-page topic overlap analysis" });
+    return { criterion: "content_cannibalization", criterion_label: "Content Cannibalization", score: 5, status: "partial", findings, fix_priority: "P3" };
+  }
+  const pageTitles = pages.map((p) => ({ title: extractPageTitle(p.html), url: p.url }));
+  const wordSets = pageTitles.map((p) => titleToWordSet(p.title));
+  const cannibalPairs = [];
+  for (let i = 0; i < pages.length; i++) {
+    for (let j = i + 1; j < pages.length; j++) {
+      const sim = jaccardSimilarity(wordSets[i], wordSets[j]);
+      if (sim > 0.6) {
+        cannibalPairs.push({
+          urlA: pageTitles[i].url.slice(0, 60),
+          urlB: pageTitles[j].url.slice(0, 60),
+          similarity: Math.round(sim * 100)
+        });
+      }
+    }
+  }
+  let score;
+  if (cannibalPairs.length === 0) {
+    score = 10;
+    findings.push({ severity: "info", detail: `${pages.length} pages analyzed - no content cannibalization detected` });
+  } else if (cannibalPairs.length === 1) {
+    score = 8;
+    findings.push({ severity: "low", detail: `1 pair of pages with overlapping topics (${cannibalPairs[0].similarity}% similarity)`, fix: "Differentiate titles and H1 headings to reduce topic overlap" });
+  } else if (cannibalPairs.length === 2) {
+    score = 5;
+    findings.push({ severity: "medium", detail: `${cannibalPairs.length} pairs of pages with overlapping topics`, fix: "Consolidate overlapping pages or differentiate their titles and content focus" });
+  } else {
+    score = 0;
+    findings.push({ severity: "high", detail: `${cannibalPairs.length} pairs of pages competing for the same topics`, fix: "Significant content overlap detected - consolidate or clearly differentiate competing pages" });
+  }
+  for (const pair of cannibalPairs.slice(0, 3)) {
+    findings.push({ severity: "low", detail: `Overlap (${pair.similarity}%): ${pair.urlA} vs ${pair.urlB}` });
+  }
+  return { criterion: "content_cannibalization", criterion_label: "Content Cannibalization", score, status: score >= 7 ? "pass" : score >= 4 ? "partial" : "fail", findings, fix_priority: score >= 7 ? "P3" : "P1" };
+}
+function checkVisibleDateSignal(data) {
+  const findings = [];
+  if (!data.homepage) {
+    findings.push({ severity: "critical", detail: "No homepage available for date signal analysis" });
+    return { criterion: "visible_date_signal", criterion_label: "Visible Date Signal", score: 0, status: "fail", findings, fix_priority: "P1" };
+  }
+  const combinedHtml = getCombinedHtml(data);
+  let score = 0;
+  const timeElements = combinedHtml.match(/<time[^>]*datetime="[^"]*"[^>]*>[^<]+<\/time>/gi) || [];
+  const hasVisibleTime = timeElements.length > 0;
+  if (hasVisibleTime) {
+    score += 5;
+    findings.push({ severity: "info", detail: `${timeElements.length} visible <time> element(s) with datetime attribute found` });
+  }
+  const ldJsonBlocks = combinedHtml.match(/<script[^>]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/gi) || [];
+  const ldJsonText = ldJsonBlocks.join(" ");
+  const hasDatePublished = /datePublished/i.test(ldJsonText);
+  const hasDateModified = /dateModified/i.test(ldJsonText);
+  const hasSchemaDate = hasDatePublished || hasDateModified;
+  if (hasSchemaDate) {
+    if (!hasVisibleTime) score += 7;
+    else score += 5;
+    const dateTypes = [hasDatePublished && "datePublished", hasDateModified && "dateModified"].filter(Boolean).join(" + ");
+    findings.push({ severity: "info", detail: `JSON-LD schema contains ${dateTypes}` });
+  }
+  const hasMetaPublished = /<meta[^>]*property="article:published_time"[^>]*>/i.test(combinedHtml);
+  const hasMetaModified = /<meta[^>]*property="article:modified_time"[^>]*>/i.test(combinedHtml);
+  const hasMetaDate = hasMetaPublished || hasMetaModified;
+  if (hasMetaDate && !hasVisibleTime && !hasSchemaDate) {
+    score += 3;
+    findings.push({ severity: "info", detail: "Article meta tags with date information found" });
+  } else if (hasMetaDate) {
+    findings.push({ severity: "info", detail: "Article meta date tags also present (supplementary)" });
+  }
+  if (hasDateModified) {
+    const dateModMatch = ldJsonText.match(/"dateModified"\s*:\s*"([^"]+)"/i);
+    if (dateModMatch) {
+      const modDate = new Date(dateModMatch[1]);
+      if (!isNaN(modDate.getTime())) {
+        const daysDiff = Math.floor((Date.now() - modDate.getTime()) / (1e3 * 60 * 60 * 24));
+        if (daysDiff <= 180) {
+          score += 1;
+          findings.push({ severity: "info", detail: `dateModified is recent (${daysDiff} days ago) - freshness bonus applied` });
+        }
+      }
+    }
+  }
+  score = Math.min(10, score);
+  if (score === 0) {
+    findings.push({ severity: "high", detail: "No visible date signals found (no <time> elements, no JSON-LD dates, no article meta dates)", fix: 'Add <time datetime="..."> elements for user-visible dates and datePublished/dateModified to JSON-LD schema' });
+  }
+  return { criterion: "visible_date_signal", criterion_label: "Visible Date Signal", score, status: score >= 7 ? "pass" : score >= 4 ? "partial" : "fail", findings, fix_priority: score >= 7 ? "P3" : "P1" };
+}
 function extractRawDataSummary(data) {
   const html = data.homepage?.text || "";
   const text = html.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ");
@@ -1513,6 +1716,48 @@ function extractRawDataSummary(data) {
       if (!data.blogSample || data.blogSample.length === 0) return false;
       const blogHtml = data.blogSample.map((p) => p.text).join("\n");
       return /faqpage/i.test(blogHtml) && /application\/ld\+json/i.test(blogHtml);
+    })(),
+    // Criteria 24-26 fields
+    question_heading_answer_rate: (() => {
+      const combinedHtml = getCombinedHtml(data);
+      const qHeadings = extractQuestionHeadings(combinedHtml);
+      if (qHeadings.length === 0) return -1;
+      let answered = 0;
+      for (const qh of qHeadings) {
+        const escaped = qh.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const pat = new RegExp(escaped + "[\\s\\S]{0,200}?<\\/h[23]>([\\s\\S]{0,1500}?)(?=<h[1-6]|$)", "i");
+        const m = pat.exec(combinedHtml);
+        if (m && m[1].replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().length >= 20) answered++;
+      }
+      return Math.round(answered / qHeadings.length * 100);
+    })(),
+    question_heading_total: extractQuestionHeadings(getCombinedHtml(data)).length,
+    cannibalizing_pairs_count: (() => {
+      const pages = [{ html: data.homepage?.text || "" }];
+      if (data.blogSample) for (const p of data.blogSample.slice(0, 5)) pages.push({ html: p.text });
+      if (pages.length <= 1) return 0;
+      const ws = pages.map((p) => titleToWordSet(extractPageTitle(p.html)));
+      let pairs = 0;
+      for (let i = 0; i < ws.length; i++) {
+        for (let j = i + 1; j < ws.length; j++) {
+          if (jaccardSimilarity(ws[i], ws[j]) > 0.6) pairs++;
+        }
+      }
+      return pairs;
+    })(),
+    page_titles_sampled: 1 + (data.blogSample?.length ?? 0),
+    has_visible_date: /<time[^>]*datetime="[^"]*"[^>]*>[^<]+<\/time>/i.test(getCombinedHtml(data)),
+    has_schema_date_in_ld: (() => {
+      const ld = (getCombinedHtml(data).match(/<script[^>]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/gi) || []).join(" ");
+      return /datePublished|dateModified/i.test(ld);
+    })(),
+    date_modified_recency_days: (() => {
+      const ld = (getCombinedHtml(data).match(/<script[^>]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/gi) || []).join(" ");
+      const m = ld.match(/"dateModified"\s*:\s*"([^"]+)"/i);
+      if (!m) return null;
+      const d = new Date(m[1]);
+      if (isNaN(d.getTime())) return null;
+      return Math.floor((Date.now() - d.getTime()) / (1e3 * 60 * 60 * 24));
     })()
   };
 }
@@ -1540,7 +1785,10 @@ function auditSiteFromData(data) {
     checkCanonicalUrl(data),
     checkContentVelocity(data),
     checkSchemaCoverage(data),
-    checkSpeakableSchema(data)
+    checkSpeakableSchema(data),
+    checkQueryAnswerAlignment(data),
+    checkContentCannibalization(data),
+    checkVisibleDateSignal(data)
   ];
 }
 
@@ -1570,7 +1818,10 @@ var WEIGHTS = {
   canonical_url: 0.04,
   content_velocity: 0.03,
   schema_coverage: 0.03,
-  speakable_schema: 0.03
+  speakable_schema: 0.03,
+  query_answer_alignment: 0.08,
+  content_cannibalization: 0.05,
+  visible_date_signal: 0.04
 };
 function calculateOverallScore(criteria) {
   let totalWeight = 0;
@@ -1692,7 +1943,10 @@ var CRITERION_LABELS = {
   "Canonical URL Strategy": "Canonical URL Strategy",
   "Content Publishing Velocity": "Content Publishing Velocity",
   "Schema Coverage & Depth": "Schema Coverage & Depth",
-  "Speakable Schema": "Speakable Schema"
+  "Speakable Schema": "Speakable Schema",
+  "Query-Answer Alignment": "Query-Answer Alignment",
+  "Content Cannibalization": "Content Cannibalization",
+  "Visible Date Signal": "Visible Date Signal"
 };
 function scoreToStatus(score) {
   if (score === 0) return "MISSING";
@@ -1800,7 +2054,10 @@ var CRITERION_WEIGHTS = {
   canonical_url: 0.04,
   content_velocity: 0.03,
   schema_coverage: 0.03,
-  speakable_schema: 0.03
+  speakable_schema: 0.03,
+  query_answer_alignment: 0.08,
+  content_cannibalization: 0.05,
+  visible_date_signal: 0.04
 };
 var OPPORTUNITY_TEMPLATES = {
   llms_txt: {
@@ -1917,6 +2174,21 @@ var OPPORTUNITY_TEMPLATES = {
     name: "Add Speakable Schema",
     effort: "Low",
     description: "Add SpeakableSpecification schema with CSS selectors pointing to key content sections. This tells voice assistants and AI engines which parts of your page are most suitable for spoken answers."
+  },
+  query_answer_alignment: {
+    name: "Improve Question-Answer Alignment",
+    effort: "Medium",
+    description: "Ensure every question-format heading (H2/H3) is followed by a direct answer paragraph. This pattern is ideal for AI engine snippet extraction."
+  },
+  content_cannibalization: {
+    name: "Resolve Content Cannibalization",
+    effort: "Medium",
+    description: "Multiple pages compete for the same topic. Consolidate overlapping pages or differentiate titles and H1 headings."
+  },
+  visible_date_signal: {
+    name: "Add Visible Date Signals",
+    effort: "Low",
+    description: "Display publication/modification dates visibly using <time> elements and add datePublished/dateModified to JSON-LD schema."
   }
 };
 function calculateImpact(score, weight, effort) {
@@ -2038,8 +2310,8 @@ function generatePitchNumbers(score, rawData, scorecard) {
   const passing = scorecard.filter((s) => s.score >= 7).length;
   metrics.push({
     metric: "Criteria Passing",
-    value: `${passing}/23`,
-    significance: passing >= 18 ? "Excellent coverage across AEO dimensions" : passing >= 12 ? "Good foundation with room to improve remaining criteria" : `${23 - passing} criteria need attention for full AI visibility`
+    value: `${passing}/26`,
+    significance: passing >= 18 ? "Excellent coverage across AEO dimensions" : passing >= 12 ? "Good foundation with room to improve remaining criteria" : `${26 - passing} criteria need attention for full AI visibility`
   });
   return metrics;
 }
@@ -2681,7 +2953,7 @@ function generateHtmlReport(result) {
 
     <div class="verdict">${escapeHtml(result.verdict)}</div>
 
-    <h2 class="section-title">Scorecard (23 Criteria)</h2>
+    <h2 class="section-title">Scorecard (26 Criteria)</h2>
     <div class="scorecard-grid">
       ${scorecardCards}
     </div>