aeorank 1.5.0 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # AEORank
 
-Score any website for AI engine visibility across 26 criteria. Pure HTTP + regex - zero API keys required.
+Score any website for AI engine visibility across 28 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)
@@ -35,42 +35,44 @@ import { audit } from 'aeorank';
 
 const result = await audit('example.com');
 console.log(result.overallScore);  // 0-100
-console.log(result.scorecard);     // 26 criteria with scores
+console.log(result.scorecard);     // 28 criteria with scores
 console.log(result.opportunities); // Prioritized improvements
 ```
 
 ## What It Checks
 
-AEORank evaluates 26 criteria across 4 categories that determine how AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) discover, parse, and cite your content:
+AEORank evaluates 28 criteria across 4 categories that determine how AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews) discover, parse, and cite your content:
 
 | # | Criterion | Weight | Category |
 |---|-----------|--------|----------|
-| 1 | llms.txt File | 10% | Discovery |
-| 2 | Schema.org Structured Data | 15% | Structure |
-| 3 | Q&A Content Format | 15% | Content |
-| 4 | Clean, Crawlable HTML | 10% | Structure |
-| 5 | Entity Authority & NAP Consistency | 10% | Authority |
-| 6 | robots.txt for AI Crawlers | 5% | Discovery |
-| 7 | Comprehensive FAQ Section | 10% | Content |
-| 8 | Original Data & Expert Analysis | 10% | Content |
-| 9 | Internal Linking Structure | 10% | Structure |
-| 10 | Semantic HTML5 & Accessibility | 5% | Structure |
-| 11 | Content Freshness Signals | 7% | Content |
-| 12 | Sitemap Completeness | 5% | Discovery |
-| 13 | RSS/Atom Feed | 3% | Discovery |
-| 14 | Table & List Extractability | 7% | Structure |
+| 1 | llms.txt File | 8% | Discovery |
+| 2 | Schema.org Structured Data | 8% | Structure |
+| 3 | Q&A Content Format | 12% | Content |
+| 4 | Clean, Crawlable HTML | 8% | Structure |
+| 5 | Entity Authority & NAP Consistency | 8% | Authority |
+| 6 | robots.txt for AI Crawlers | 3% | Discovery |
+| 7 | Comprehensive FAQ Section | 8% | Content |
+| 8 | Original Data & Expert Analysis | 12% | Content |
+| 9 | Internal Linking Structure | 8% | Structure |
+| 10 | Semantic HTML5 & Accessibility | 4% | Structure |
+| 11 | Content Freshness Signals | 6% | Content |
+| 12 | Sitemap Completeness | 3% | Discovery |
+| 13 | RSS/Atom Feed | 2% | Discovery |
+| 14 | Table & List Extractability | 5% | Structure |
 | 15 | Definition Patterns | 4% | Content |
 | 16 | Direct Answer Paragraphs | 7% | Content |
-| 17 | Content Licensing & AI Permissions | 4% | Discovery |
+| 17 | Content Licensing & AI Permissions | 3% | Discovery |
 | 18 | Author & Expert Schema | 4% | Authority |
-| 19 | Fact & Data Density | 5% | Content |
-| 20 | Canonical URL Strategy | 4% | Structure |
+| 19 | Fact & Data Density | 8% | Content |
+| 20 | Canonical URL Strategy | 2% | Structure |
 | 21 | Content Publishing Velocity | 3% | Content |
-| 22 | Schema Coverage & Depth | 3% | Structure |
-| 23 | Speakable Schema | 3% | Structure |
-| 24 | Query-Answer Alignment | 8% | Content |
+| 22 | Schema Coverage & Depth | 2% | Structure |
+| 23 | Speakable Schema | 2% | Structure |
+| 24 | Query-Answer Alignment | 6% | Content |
 | 25 | Content Cannibalization | 5% | Content |
 | 26 | Visible Date Signal | 4% | Content |
+| 27 | **Topic Coherence** | **14%** | **Content** |
+| 28 | **Content Depth** | **6%** | **Content** |
 
 ## CLI Options
 
@@ -99,7 +101,7 @@ Use the built-in action to gate deployments on AEO score:
 
 ```yaml
 - name: AEO Audit
-  uses: AEO-Content-Inc/aeorank@v1
+  uses: AEO-Content-Inc/aeorank@v2
   with:
     domain: example.com
     threshold: 70
@@ -119,7 +121,7 @@ Or use `npx` directly:
 Run a complete audit. Returns `AuditResult` with:
 
 - `overallScore` - 0-100 weighted score
-- `scorecard` - 26 `ScoreCardItem` entries (criterion, score 0-10, status, key findings)
+- `scorecard` - 28 `ScoreCardItem` entries (criterion, score 0-10, status, key findings)
 - `detailedFindings` - Per-criterion findings with severity
 - `opportunities` - Prioritized improvements with effort/impact
 - `pitchNumbers` - Key metrics (schema types, AI crawler access, etc.)
@@ -150,6 +152,55 @@ Score a single HTML page against 14 per-page AEO criteria. Returns `PageScoreRes
 
 Batch-score all pages (homepage + blogSample) from a `SiteData` object. Returns `PageScoreResult[]`.
 
+### `buildLinkGraph(pages, domain, homepageUrl)`
+
+Analyze internal linking structure from crawled pages. Returns `LinkGraph` with:
+
+- `nodes` - Map of URL to `PageNode` (in/out degree, depth, pillar/hub/orphan flags)
+- `edges` - Array of `LinkEdge` (from, to, anchor text)
+- `stats` - `LinkGraphStats` (total pages, orphans, pillars, hubs, avg depth, clusters)
+- `clusters` - `TopicCluster[]` (pillar URL, spoke URLs, cohesion score)
+
+```ts
+import { crawlFullSite, prefetchSiteData, buildLinkGraph } from 'aeorank';
+
+const siteData = await prefetchSiteData('example.com');
+const crawl = await crawlFullSite(siteData, { maxPages: 200 });
+const graph = buildLinkGraph(crawl.pages, 'example.com', 'https://example.com');
+
+console.log(graph.stats.orphanPages);   // Pages with no inbound links
+console.log(graph.stats.pillarPages);   // High-authority hub pages
+console.log(graph.clusters);            // Topic clusters detected
+```
+
+### `generateFixPlan(domain, score, criteria, pages?, linkGraph?)`
+
+Generate a phased fix plan from audit results. Returns `FixPlan` with:
+
+- `phases` - 4 phases (Foundation, Content, Authority, Architecture) with prioritized `FixAction[]`
+- `quickWins` - Low-effort, high-impact fixes
+- `projectedScore` - Estimated score after applying all fixes
+- `summary` - Counts by impact level, top opportunity, estimated effort
+
+Each `FixAction` includes: title, description, impact/effort levels, step-by-step instructions, code examples, affected pages, and dependency ordering.
+
+```ts
+import { audit, generateFixPlan } from 'aeorank';
+
+const result = await audit('example.com');
+const plan = generateFixPlan(
+  'example.com',
+  result.overallScore,
+  result.criterionResults,
+  result.pagesReviewed,
+);
+
+console.log(plan.projectedScore);           // e.g. 82
+console.log(plan.quickWins[0].title);       // e.g. "Add llms.txt file"
+console.log(plan.quickWins[0].impactScore); // e.g. 10
+console.log(plan.phases[0].fixes.length);   // Foundation phase fixes
+```
+
 ### Advanced API
 
 For custom pipelines, import individual stages:
@@ -165,6 +216,8 @@ import {
   generateOpportunities,
   scorePage,
   scoreAllPages,
+  buildLinkGraph,
+  generateFixPlan,
   isSpaShell,
   fetchWithHeadless,
 } from 'aeorank';
@@ -174,6 +227,24 @@ const results = auditSiteFromData(siteData);
 const score = calculateOverallScore(results);
 ```
 
+### Browser Entry Point
+
+For browser environments (Chrome extensions, web apps), import from `aeorank/browser` to avoid Node.js dependencies (Puppeteer, fs):
+
+```ts
+import {
+  prefetchSiteData,
+  auditSiteFromData,
+  calculateOverallScore,
+  buildLinkGraph,
+  generateFixPlan,
+  analyzeAllPages,
+  crawlFullSite,
+} from 'aeorank/browser';
+```
+
+The browser entry exports everything except `headless-fetch` (Puppeteer), `html-report` (Node fs), `audit` orchestrator, and CLI.
+
 ## SPA Support
 
 Sites that use client-side rendering (React, Vue, Angular) return empty HTML shells to regular HTTP requests. AEORank detects these automatically and re-renders them with Puppeteer if available.
@@ -188,7 +259,7 @@ Use `--no-headless` to skip SPA rendering (faster but may produce lower scores f
 
 ## Full-Site Crawl
 
-By default, AEORank audits the homepage plus ~20 discovered pages. For deeper analysis, enable `--full-crawl` to BFS-crawl every discoverable page:
+By default, AEORank audits the homepage plus up to 50 blog pages from the sitemap. For deeper analysis, enable `--full-crawl` to BFS-crawl every discoverable page:
 
 ```bash
 npx aeorank example.com --full-crawl                    # Up to 200 pages
@@ -227,7 +298,7 @@ AEORank scores each individual page (0-100) against the 14 criteria that apply a
 
 The 14 per-page criteria: Schema.org Structured Data, Q&A Content Format, Clean Crawlable HTML, FAQ Section Content, Original Data & Expert Content, Query-Answer Alignment, Content Freshness Signals, Table & List Extractability, Direct Answer Paragraphs, Semantic HTML5 & Accessibility, Fact & Data Density, Definition Patterns, Canonical URL Strategy, Visible Date Signal.
 
-The remaining 12 criteria (llms.txt, robots.txt, sitemap, RSS, entity consistency, internal linking, content licensing, author schema, content velocity, schema coverage, speakable schema, content cannibalization) are site-level only.
+The remaining 14 criteria (llms.txt, robots.txt, sitemap, RSS, entity consistency, internal linking, content licensing, author schema, content velocity, schema coverage, speakable schema, content cannibalization, topic coherence, content depth) are site-level only.
 
 ### CLI Output
 
@@ -258,6 +329,70 @@ console.log(result.criterionScores);  // 14 per-criterion scores
 const allScores = scoreAllPages(siteData);
 ```
 
+## Link Graph Analysis
+
+Analyze your site's internal linking structure to find orphan pages, identify pillar content, and detect topic clusters:
+
+```bash
+npx aeorank example.com --full-crawl --json | jq '.linkGraph.stats'
+```
+
+```ts
+import { crawlFullSite, prefetchSiteData, buildLinkGraph, serializeLinkGraph } from 'aeorank';
+
+const siteData = await prefetchSiteData('example.com');
+const crawl = await crawlFullSite(siteData, { maxPages: 200 });
+const graph = buildLinkGraph(crawl.pages, 'example.com', 'https://example.com');
+
+// Orphan pages (no inbound links - invisible to crawlers)
+const orphans = [...graph.nodes.values()].filter(n => n.isOrphan);
+
+// Pillar pages (high authority, many inbound links)
+const pillars = [...graph.nodes.values()].filter(n => n.isPillar);
+
+// Topic clusters (pillar + spoke pages with high cohesion)
+graph.clusters.forEach(c => {
+  console.log(`${c.pillarTitle}: ${c.spokes.length} spokes, cohesion ${c.cohesion}`);
+});
+
+// Serialize for storage/transport (Map -> plain object)
+const json = serializeLinkGraph(graph);
+```
+
+## Fix Plan Engine
+
+Generate actionable, phased fix plans from audit results. Each fix includes step-by-step instructions, code examples, effort/impact ratings, and dependency ordering:
+
+```bash
+npx aeorank example.com --full-crawl --json | jq '.fixPlan'
+```
+
+```ts
+import { audit, generateFixPlan } from 'aeorank';
+
+const result = await audit('example.com', { fullCrawl: true });
+const plan = generateFixPlan(
+  'example.com',
+  result.overallScore,
+  result.criterionResults,
+  result.pagesReviewed,
+  result.linkGraph,  // optional - enables link-aware fixes
+);
+
+// 4 phases: Foundation -> Content -> Authority -> Architecture
+plan.phases.forEach(phase => {
+  console.log(`${phase.title}: ${phase.fixes.length} fixes`);
+});
+
+// Quick wins: low effort + high impact
+plan.quickWins.forEach(qw => {
+  console.log(`${qw.title} (+${qw.impactScore} pts) - ${qw.effort} effort`);
+  qw.steps.forEach(s => console.log(`  - ${s}`));
+});
+
+console.log(`Current: ${plan.overallScore} -> Projected: ${plan.projectedScore}`);
+```
+
 ## Scoring
 
 Each criterion is scored 0-10 by deterministic checks (regex, HTML parsing, HTTP headers). The overall score is a weighted average normalized to 0-100.
@@ -316,7 +451,7 @@ console.log(result.comparison.tied);              // Criteria with equal scores
 
 ## Benchmark Dataset
 
-The `data/` directory contains the largest open dataset of AI visibility scores - **13,619 domains** scored across 26 criteria, including **4,328 Y Combinator startups** across 48 batches (W06-W26):
+The `data/` directory contains the largest open dataset of AI visibility scores - **13,619 domains** scored across 28 criteria, including **4,328 Y Combinator startups** across 48 batches (W06-W26):
 
 | File | Contents |
 |------|----------|