aeorank 1.4.0 → 1.6.0

package/README.md

@@ -125,7 +125,7 @@ Run a complete audit. Returns `AuditResult` with:
 - `pitchNumbers` - Key metrics (schema types, AI crawler access, etc.)
 - `verdict` - Human-readable summary paragraph
 - `bottomLine` - Actionable recommendation
-- `pagesReviewed` - Per-page analysis with issues and strengths
+- `pagesReviewed` - Per-page analysis with issues, strengths, and AEO score (0-100)
 - `elapsed` - Wall-clock seconds
 
 **Options:**
@@ -139,6 +139,66 @@ Run a complete audit. Returns `AuditResult` with:
 | `maxPages` | `number` | `200` | Max pages for full crawl |
 | `concurrency` | `number` | `5` | Parallel fetches for full crawl |
 
+### `scorePage(html, url?)`
+
+Score a single HTML page against 14 per-page AEO criteria. Returns `PageScoreResult` with:
+
+- `aeoScore` - 0-100 weighted score
+- `criterionScores` - 14 `PageCriterionScore` entries (criterion, score 0-10, weight)
+
+### `scoreAllPages(siteData)`
+
+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:
@@ -152,6 +212,10 @@ import {
   buildDetailedFindings,
   generateVerdict,
   generateOpportunities,
+  scorePage,
+  scoreAllPages,
+  buildLinkGraph,
+  generateFixPlan,
   isSpaShell,
   fetchWithHeadless,
 } from 'aeorank';
@@ -161,6 +225,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.
@@ -208,6 +290,107 @@ console.log(crawlResult.pages.length);         // Pages fetched
 console.log(crawlResult.discoveredUrls.length); // Total URLs found
 ```
 
+## Per-Page Scoring
+
+AEORank scores each individual page (0-100) against the 14 criteria that apply at page level. Instead of only seeing "your site scores 62," you get "your /about page scores 45, your /blog/guide scores 78."
+
+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.
+
+### CLI Output
+
+Per-page scores appear in the pages section:
+
+```
+Pages reviewed (47):
+  Homepage  https://example.com                      0 issues [AEO: 72]
+  Blog      https://example.com/blog/post            2 issues [AEO: 58]
+
+  Average page AEO score: 62/100
+  Top:    /blog/medicare-walkers-guide (92)
+  Bottom: /thank-you (23)
+```
+
+### Programmatic API
+
+```ts
+import { scorePage, scoreAllPages } from 'aeorank';
+import type { PageScoreResult, PageCriterionScore } from 'aeorank';
+
+// Score a single page
+const result = scorePage(html, url);
+console.log(result.aeoScore);         // 0-100
+console.log(result.criterionScores);  // 14 per-criterion scores
+
+// Score all pages from site data
+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.
@@ -266,7 +449,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 23 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 26 criteria, including **4,328 Y Combinator startups** across 48 batches (W06-W26):
 
 | File | Contents |
 |------|----------|