aeorank 1.4.0 → 1.6.0

package/dist/index.d.cts

@@ -36,18 +36,26 @@ interface PitchMetric {
     significance: string;
 }
 type PageCategory$1 = 'homepage' | 'blog' | 'about' | 'pricing' | 'services' | 'contact' | 'team' | 'resources' | 'docs' | 'cases' | 'faq' | 'content';
-interface PageIssue$1 {
+interface PageCriterionScore$1 {
+    criterion: string;
+    criterion_label: string;
+    score: number;
+    weight: number;
+}
+interface PageIssue {
     check: string;
     label: string;
     severity: 'error' | 'warning' | 'info';
 }
-interface PageReview$1 {
+interface PageReview {
     url: string;
     title: string;
     category: PageCategory$1;
     wordCount: number;
-    issues: PageIssue$1[];
-    strengths: PageIssue$1[];
+    issues: PageIssue[];
+    strengths: PageIssue[];
+    aeoScore?: number;
+    criterionScores?: PageCriterionScore$1[];
 }
 interface AuditData {
     site: string;
@@ -61,7 +69,7 @@ interface AuditData {
     opportunities: Deliverable[];
     pitchNumbers: PitchMetric[];
     bottomLine: string;
-    pagesReviewed?: PageReview$1[];
+    pagesReviewed?: PageReview[];
 }
 type AuditStatus = 'pass' | 'fail' | 'partial' | 'not_found';
 type Priority = 'P0' | 'P1' | 'P2' | 'P3';
@@ -109,6 +117,93 @@ interface AuditResult extends AuditData {
  */
 declare function audit(domain: string, options?: AuditOptions): Promise<AuditResult>;
 
+/**
+ * Link graph analysis for full-site AEO audits.
+ * Builds an internal link graph, detects orphan pages, pillar pages,
+ * hub pages, and topic clusters from crawled page data.
+ */
+
+interface LinkEdge {
+    source: string;
+    target: string;
+    anchorText: string;
+}
+interface PageNode {
+    url: string;
+    title: string;
+    wordCount: number;
+    category: PageCategory;
+    inDegree: number;
+    outDegree: number;
+    depth: number;
+    isPillar: boolean;
+    isHub: boolean;
+    isOrphan: boolean;
+}
+interface TopicCluster {
+    pillarUrl: string;
+    pillarTitle: string;
+    spokes: string[];
+    cohesion: number;
+}
+interface LinkGraphStats {
+    totalPages: number;
+    totalEdges: number;
+    orphanPages: number;
+    pillarPages: number;
+    hubPages: number;
+    avgDepth: number;
+    maxDepth: number;
+    clusters: number;
+}
+interface LinkGraph {
+    nodes: Map<string, PageNode>;
+    edges: LinkEdge[];
+    stats: LinkGraphStats;
+    clusters: TopicCluster[];
+}
+interface SerializedLinkGraph {
+    nodes: PageNode[];
+    stats: LinkGraphStats;
+    clusters: TopicCluster[];
+}
+declare function serializeLinkGraph(graph: LinkGraph): SerializedLinkGraph;
+/**
+ * Extract internal links from HTML with their anchor text.
+ * Similar to extractInternalLinks in full-site-crawler.ts but returns LinkEdge[].
+ */
+declare function extractLinksWithAnchors(html: string, sourceUrl: string, domain: string): LinkEdge[];
+/**
+ * BFS from homepage to compute click depth for each node.
+ * Unreachable pages get Infinity.
+ */
+declare function calculateDepths(nodes: Map<string, PageNode>, adjacency: Map<string, Set<string>>, homepageUrl: string): void;
+/**
+ * Detect pillar pages: long content with significant in/out linking.
+ * wordCount >= 1500 AND inDegree >= 3 AND outDegree >= 3
+ * AND category in blog/content/resources/docs AND not homepage (depth > 0).
+ */
+declare function detectPillars(nodes: Map<string, PageNode>): void;
+/**
+ * Detect hub pages: high outDegree navigation/index pages.
+ * outDegree >= 10 with category homepage/resources/docs, OR outDegree >= 15.
+ */
+declare function detectHubs(nodes: Map<string, PageNode>): void;
+/**
+ * Detect topic clusters around pillar pages.
+ * For each pillar, gather spokes (pages linked to/from pillar).
+ * Cohesion = actual edges between cluster members / possible edges.
+ * Minimum 2 spokes to form a cluster.
+ */
+declare function detectClusters(nodes: Map<string, PageNode>, edges: LinkEdge[]): TopicCluster[];
+/**
+ * Build a link graph from crawled pages.
+ * @param pages - Array of FetchResult from full-site crawl
+ * @param domain - The site domain
+ * @param homepageUrl - Full URL of the homepage (e.g. https://example.com)
+ */
+declare function buildLinkGraph(pages: FetchResult[], domain: string, homepageUrl: string): LinkGraph;
+
 interface CriterionResult {
     criterion: string;
     criterion_label: string;
@@ -147,6 +242,8 @@ interface SiteData {
         skipped: number;
         elapsed: number;
     };
+    /** Link graph from full-site crawl */
+    linkGraph?: LinkGraph;
 }
 interface RawDataSummary {
     domain: string;
@@ -260,22 +357,35 @@ declare function generateBottomLine(score: number, opportunities: Deliverable[],
  * Runs 12 deterministic checks on each crawled page (no LLM).
  */
 
-interface PageIssue {
-    check: string;
-    label: string;
-    severity: 'error' | 'warning' | 'info';
-}
-interface PageReview {
-    url: string;
-    title: string;
-    category: PageCategory;
-    wordCount: number;
-    issues: PageIssue[];
-    strengths: PageIssue[];
-}
 declare function analyzePage(html: string, url: string, category: PageCategory): PageReview;
 declare function analyzeAllPages(siteData: SiteData): PageReview[];
 
+/**
+ * Per-page AEO scoring.
+ * Evaluates 14 of 26 criteria that apply at individual page level.
+ * Produces a 0-100 AEO score per page.
+ */
+
+interface PageCriterionScore {
+    criterion: string;
+    criterion_label: string;
+    score: number;
+    weight: number;
+}
+interface PageScoreResult {
+    aeoScore: number;
+    criterionScores: PageCriterionScore[];
+}
+/**
+ * Score a single page against 14 AEO criteria.
+ * Returns a 0-100 AEO score and individual criterion scores.
+ */
+declare function scorePage(html: string, url?: string): PageScoreResult;
+/**
+ * Score all crawled pages (homepage + blogSample).
+ */
+declare function scoreAllPages(siteData: SiteData): PageScoreResult[];
+
 /**
  * Extended page discovery for instant audit.
  * Fetches additional pages beyond what prefetchSiteData provides,
@@ -399,6 +509,58 @@ interface ParkedDomainResult {
  */
 declare function detectParkedDomain(bodySnippet: string): ParkedDomainResult;
 
+/**
+ * Fix Plan Engine - generates actionable, phased fix plans from audit scores.
+ * Runs alongside the existing opportunities system (no breaking changes).
+ * Uses criterion scores, optional per-page data, and optional link graph
+ * to produce structured fix plans with code examples and dependency ordering.
+ */
+
+interface FixAction {
+    id: string;
+    criterion: string;
+    criterionId: string;
+    title: string;
+    description: string;
+    impact: 'critical' | 'high' | 'medium' | 'low';
+    effort: 'trivial' | 'low' | 'medium' | 'high';
+    impactScore: number;
+    category: 'content' | 'structure' | 'discovery' | 'trust';
+    steps: string[];
+    codeExample?: string;
+    successCriteria: string;
+    dependsOn?: string[];
+    affectedPages?: string[];
+    pageCount?: number;
+}
+interface FixPhase {
+    phase: number;
+    title: string;
+    description: string;
+    fixes: FixAction[];
+    estimatedImpact: number;
+}
+interface FixPlanSummary {
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+    quickWinCount: number;
+    topOpportunity: string;
+    estimatedTotalEffort: string;
+}
+interface FixPlan {
+    domain: string;
+    generatedAt: string;
+    overallScore: number;
+    projectedScore: number;
+    totalFixes: number;
+    phases: FixPhase[];
+    quickWins: FixAction[];
+    summary: FixPlanSummary;
+}
+declare function generateFixPlan(domain: string, overallScore: number, criteria: CriterionResult[], pagesReviewed?: PageReview[], linkGraph?: LinkGraph): FixPlan;
+
 /**
  * HTML report generator for AEORank audits.
  * Produces self-contained HTML with inline CSS - zero external dependencies.
@@ -456,4 +618,4 @@ interface ComparisonResult {
  */
 declare function compare(domainA: string, domainB: string, options?: AuditOptions): Promise<ComparisonResult>;
 
-export { type AuditData, type AuditFinding, type AuditOptions, type AuditResult, type AuditStatus, CRITERION_LABELS, type ComparisonResult, type CrawlOptions, type CrawlResult, type CriterionComparison, type CriterionDetail, type CriterionResult, type Deliverable, type DetailedFinding, type FetchResult, type FindingSeverity, type FindingType, type HeadlessOptions, type ImpactLevel, type PageCategory$1 as PageCategory, type PageIssue$1 as PageIssue, type PageReview$1 as PageReview, type ParkedDomainResult, type PitchMetric, type Priority, type RawDataSummary, type RenderingMethod, type ScoreCardItem, type Severity, type SiteData, type Status, analyzeAllPages, analyzePage, audit, auditSiteFromData, buildDetailedFindings, buildScorecard, calculateOverallScore, classifyRendering, compare, crawlFullSite, detectParkedDomain, extractAllUrlsFromSitemap, extractContentPagesFromSitemap, extractInternalLinks, extractNavLinks, extractRawDataSummary, fetchMultiPageData, fetchWithHeadless, generateBottomLine, generateComparisonHtmlReport, generateHtmlReport, generateOpportunities, generatePitchNumbers, generateVerdict, inferCategory, isSpaShell, prefetchSiteData, scoreToStatus };
+export { type AuditData, type AuditFinding, type AuditOptions, type AuditResult, type AuditStatus, CRITERION_LABELS, type ComparisonResult, type CrawlOptions, type CrawlResult, type CriterionComparison, type CriterionDetail, type CriterionResult, type Deliverable, type DetailedFinding, type FetchResult, type FindingSeverity, type FindingType, type FixAction, type FixPhase, type FixPlan, type FixPlanSummary, type HeadlessOptions, type ImpactLevel, type LinkEdge, type LinkGraph, type LinkGraphStats, type PageCategory$1 as PageCategory, type PageCriterionScore$1 as PageCriterionScore, type PageIssue, type PageNode, type PageReview, type PageScoreResult, type ParkedDomainResult, type PitchMetric, type Priority, type RawDataSummary, type RenderingMethod, type ScoreCardItem, type SerializedLinkGraph, type Severity, type SiteData, type Status, type TopicCluster, analyzeAllPages, analyzePage, audit, auditSiteFromData, buildDetailedFindings, buildLinkGraph, buildScorecard, calculateDepths, calculateOverallScore, classifyRendering, compare, crawlFullSite, detectClusters, detectHubs, detectParkedDomain, detectPillars, extractAllUrlsFromSitemap, extractContentPagesFromSitemap, extractInternalLinks, extractLinksWithAnchors, extractNavLinks, extractRawDataSummary, fetchMultiPageData, fetchWithHeadless, generateBottomLine, generateComparisonHtmlReport, generateFixPlan, generateHtmlReport, generateOpportunities, generatePitchNumbers, generateVerdict, inferCategory, isSpaShell, prefetchSiteData, scoreAllPages, scorePage, scoreToStatus, serializeLinkGraph };

package/dist/index.d.ts

@@ -36,18 +36,26 @@ interface PitchMetric {
     significance: string;
 }
 type PageCategory$1 = 'homepage' | 'blog' | 'about' | 'pricing' | 'services' | 'contact' | 'team' | 'resources' | 'docs' | 'cases' | 'faq' | 'content';
-interface PageIssue$1 {
+interface PageCriterionScore$1 {
+    criterion: string;
+    criterion_label: string;
+    score: number;
+    weight: number;
+}
+interface PageIssue {
     check: string;
     label: string;
     severity: 'error' | 'warning' | 'info';
 }
-interface PageReview$1 {
+interface PageReview {
     url: string;
     title: string;
     category: PageCategory$1;
     wordCount: number;
-    issues: PageIssue$1[];
-    strengths: PageIssue$1[];
+    issues: PageIssue[];
+    strengths: PageIssue[];
+    aeoScore?: number;
+    criterionScores?: PageCriterionScore$1[];
 }
 interface AuditData {
     site: string;
@@ -61,7 +69,7 @@ interface AuditData {
     opportunities: Deliverable[];
     pitchNumbers: PitchMetric[];
     bottomLine: string;
-    pagesReviewed?: PageReview$1[];
+    pagesReviewed?: PageReview[];
 }
 type AuditStatus = 'pass' | 'fail' | 'partial' | 'not_found';
 type Priority = 'P0' | 'P1' | 'P2' | 'P3';
@@ -109,6 +117,93 @@ interface AuditResult extends AuditData {
  */
 declare function audit(domain: string, options?: AuditOptions): Promise<AuditResult>;
 
+/**
+ * Link graph analysis for full-site AEO audits.
+ * Builds an internal link graph, detects orphan pages, pillar pages,
+ * hub pages, and topic clusters from crawled page data.
+ */
+
+interface LinkEdge {
+    source: string;
+    target: string;
+    anchorText: string;
+}
+interface PageNode {
+    url: string;
+    title: string;
+    wordCount: number;
+    category: PageCategory;
+    inDegree: number;
+    outDegree: number;
+    depth: number;
+    isPillar: boolean;
+    isHub: boolean;
+    isOrphan: boolean;
+}
+interface TopicCluster {
+    pillarUrl: string;
+    pillarTitle: string;
+    spokes: string[];
+    cohesion: number;
+}
+interface LinkGraphStats {
+    totalPages: number;
+    totalEdges: number;
+    orphanPages: number;
+    pillarPages: number;
+    hubPages: number;
+    avgDepth: number;
+    maxDepth: number;
+    clusters: number;
+}
+interface LinkGraph {
+    nodes: Map<string, PageNode>;
+    edges: LinkEdge[];
+    stats: LinkGraphStats;
+    clusters: TopicCluster[];
+}
+interface SerializedLinkGraph {
+    nodes: PageNode[];
+    stats: LinkGraphStats;
+    clusters: TopicCluster[];
+}
+declare function serializeLinkGraph(graph: LinkGraph): SerializedLinkGraph;
+/**
+ * Extract internal links from HTML with their anchor text.
+ * Similar to extractInternalLinks in full-site-crawler.ts but returns LinkEdge[].
+ */
+declare function extractLinksWithAnchors(html: string, sourceUrl: string, domain: string): LinkEdge[];
+/**
+ * BFS from homepage to compute click depth for each node.
+ * Unreachable pages get Infinity.
+ */
+declare function calculateDepths(nodes: Map<string, PageNode>, adjacency: Map<string, Set<string>>, homepageUrl: string): void;
+/**
+ * Detect pillar pages: long content with significant in/out linking.
+ * wordCount >= 1500 AND inDegree >= 3 AND outDegree >= 3
+ * AND category in blog/content/resources/docs AND not homepage (depth > 0).
+ */
+declare function detectPillars(nodes: Map<string, PageNode>): void;
+/**
+ * Detect hub pages: high outDegree navigation/index pages.
+ * outDegree >= 10 with category homepage/resources/docs, OR outDegree >= 15.
+ */
+declare function detectHubs(nodes: Map<string, PageNode>): void;
+/**
+ * Detect topic clusters around pillar pages.
+ * For each pillar, gather spokes (pages linked to/from pillar).
+ * Cohesion = actual edges between cluster members / possible edges.
+ * Minimum 2 spokes to form a cluster.
+ */
+declare function detectClusters(nodes: Map<string, PageNode>, edges: LinkEdge[]): TopicCluster[];
+/**
+ * Build a link graph from crawled pages.
+ * @param pages - Array of FetchResult from full-site crawl
+ * @param domain - The site domain
+ * @param homepageUrl - Full URL of the homepage (e.g. https://example.com)
+ */
+declare function buildLinkGraph(pages: FetchResult[], domain: string, homepageUrl: string): LinkGraph;
+
 interface CriterionResult {
     criterion: string;
     criterion_label: string;
@@ -147,6 +242,8 @@ interface SiteData {
         skipped: number;
         elapsed: number;
     };
+    /** Link graph from full-site crawl */
+    linkGraph?: LinkGraph;
 }
 interface RawDataSummary {
     domain: string;
@@ -260,22 +357,35 @@ declare function generateBottomLine(score: number, opportunities: Deliverable[],
  * Runs 12 deterministic checks on each crawled page (no LLM).
  */
 
-interface PageIssue {
-    check: string;
-    label: string;
-    severity: 'error' | 'warning' | 'info';
-}
-interface PageReview {
-    url: string;
-    title: string;
-    category: PageCategory;
-    wordCount: number;
-    issues: PageIssue[];
-    strengths: PageIssue[];
-}
 declare function analyzePage(html: string, url: string, category: PageCategory): PageReview;
 declare function analyzeAllPages(siteData: SiteData): PageReview[];
 
+/**
+ * Per-page AEO scoring.
+ * Evaluates 14 of 26 criteria that apply at individual page level.
+ * Produces a 0-100 AEO score per page.
+ */
+
+interface PageCriterionScore {
+    criterion: string;
+    criterion_label: string;
+    score: number;
+    weight: number;
+}
+interface PageScoreResult {
+    aeoScore: number;
+    criterionScores: PageCriterionScore[];
+}
+/**
+ * Score a single page against 14 AEO criteria.
+ * Returns a 0-100 AEO score and individual criterion scores.
+ */
+declare function scorePage(html: string, url?: string): PageScoreResult;
+/**
+ * Score all crawled pages (homepage + blogSample).
+ */
+declare function scoreAllPages(siteData: SiteData): PageScoreResult[];
+
 /**
  * Extended page discovery for instant audit.
  * Fetches additional pages beyond what prefetchSiteData provides,
@@ -399,6 +509,58 @@ interface ParkedDomainResult {
  */
 declare function detectParkedDomain(bodySnippet: string): ParkedDomainResult;
 
+/**
+ * Fix Plan Engine - generates actionable, phased fix plans from audit scores.
+ * Runs alongside the existing opportunities system (no breaking changes).
+ * Uses criterion scores, optional per-page data, and optional link graph
+ * to produce structured fix plans with code examples and dependency ordering.
+ */
+
+interface FixAction {
+    id: string;
+    criterion: string;
+    criterionId: string;
+    title: string;
+    description: string;
+    impact: 'critical' | 'high' | 'medium' | 'low';
+    effort: 'trivial' | 'low' | 'medium' | 'high';
+    impactScore: number;
+    category: 'content' | 'structure' | 'discovery' | 'trust';
+    steps: string[];
+    codeExample?: string;
+    successCriteria: string;
+    dependsOn?: string[];
+    affectedPages?: string[];
+    pageCount?: number;
+}
+interface FixPhase {
+    phase: number;
+    title: string;
+    description: string;
+    fixes: FixAction[];
+    estimatedImpact: number;
+}
+interface FixPlanSummary {
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+    quickWinCount: number;
+    topOpportunity: string;
+    estimatedTotalEffort: string;
+}
+interface FixPlan {
+    domain: string;
+    generatedAt: string;
+    overallScore: number;
+    projectedScore: number;
+    totalFixes: number;
+    phases: FixPhase[];
+    quickWins: FixAction[];
+    summary: FixPlanSummary;
+}
+declare function generateFixPlan(domain: string, overallScore: number, criteria: CriterionResult[], pagesReviewed?: PageReview[], linkGraph?: LinkGraph): FixPlan;
+
 /**
  * HTML report generator for AEORank audits.
  * Produces self-contained HTML with inline CSS - zero external dependencies.
@@ -456,4 +618,4 @@ interface ComparisonResult {
  */
 declare function compare(domainA: string, domainB: string, options?: AuditOptions): Promise<ComparisonResult>;
 
-export { type AuditData, type AuditFinding, type AuditOptions, type AuditResult, type AuditStatus, CRITERION_LABELS, type ComparisonResult, type CrawlOptions, type CrawlResult, type CriterionComparison, type CriterionDetail, type CriterionResult, type Deliverable, type DetailedFinding, type FetchResult, type FindingSeverity, type FindingType, type HeadlessOptions, type ImpactLevel, type PageCategory$1 as PageCategory, type PageIssue$1 as PageIssue, type PageReview$1 as PageReview, type ParkedDomainResult, type PitchMetric, type Priority, type RawDataSummary, type RenderingMethod, type ScoreCardItem, type Severity, type SiteData, type Status, analyzeAllPages, analyzePage, audit, auditSiteFromData, buildDetailedFindings, buildScorecard, calculateOverallScore, classifyRendering, compare, crawlFullSite, detectParkedDomain, extractAllUrlsFromSitemap, extractContentPagesFromSitemap, extractInternalLinks, extractNavLinks, extractRawDataSummary, fetchMultiPageData, fetchWithHeadless, generateBottomLine, generateComparisonHtmlReport, generateHtmlReport, generateOpportunities, generatePitchNumbers, generateVerdict, inferCategory, isSpaShell, prefetchSiteData, scoreToStatus };
+export { type AuditData, type AuditFinding, type AuditOptions, type AuditResult, type AuditStatus, CRITERION_LABELS, type ComparisonResult, type CrawlOptions, type CrawlResult, type CriterionComparison, type CriterionDetail, type CriterionResult, type Deliverable, type DetailedFinding, type FetchResult, type FindingSeverity, type FindingType, type FixAction, type FixPhase, type FixPlan, type FixPlanSummary, type HeadlessOptions, type ImpactLevel, type LinkEdge, type LinkGraph, type LinkGraphStats, type PageCategory$1 as PageCategory, type PageCriterionScore$1 as PageCriterionScore, type PageIssue, type PageNode, type PageReview, type PageScoreResult, type ParkedDomainResult, type PitchMetric, type Priority, type RawDataSummary, type RenderingMethod, type ScoreCardItem, type SerializedLinkGraph, type Severity, type SiteData, type Status, type TopicCluster, analyzeAllPages, analyzePage, audit, auditSiteFromData, buildDetailedFindings, buildLinkGraph, buildScorecard, calculateDepths, calculateOverallScore, classifyRendering, compare, crawlFullSite, detectClusters, detectHubs, detectParkedDomain, detectPillars, extractAllUrlsFromSitemap, extractContentPagesFromSitemap, extractInternalLinks, extractLinksWithAnchors, extractNavLinks, extractRawDataSummary, fetchMultiPageData, fetchWithHeadless, generateBottomLine, generateComparisonHtmlReport, generateFixPlan, generateHtmlReport, generateOpportunities, generatePitchNumbers, generateVerdict, inferCategory, isSpaShell, prefetchSiteData, scoreAllPages, scorePage, scoreToStatus, serializeLinkGraph };