aeorank 1.5.0 → 2.0.0

package/dist/index.d.cts

@@ -117,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;
@@ -146,7 +233,7 @@ interface SiteData {
     redirectedTo: string | null;
     /** Set when homepage is a parked/for-sale/lost domain */
     parkedReason: string | null;
-    /** Sampled blog/content pages from sitemap (up to 5) */
+    /** Sampled blog/content pages from sitemap (up to 50) */
     blogSample?: FetchResult[];
     /** Full-crawl statistics (set when --full-crawl is used) */
     crawlStats?: {
@@ -155,6 +242,8 @@ interface SiteData {
         skipped: number;
         elapsed: number;
     };
+    /** Link graph from full-site crawl */
+    linkGraph?: LinkGraph;
 }
 interface RawDataSummary {
     domain: string;
@@ -420,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.
@@ -477,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 PageCriterionScore$1 as PageCriterionScore, type PageIssue, type PageReview, type PageScoreResult, 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, scoreAllPages, scorePage, 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

@@ -117,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;
@@ -146,7 +233,7 @@ interface SiteData {
     redirectedTo: string | null;
     /** Set when homepage is a parked/for-sale/lost domain */
     parkedReason: string | null;
-    /** Sampled blog/content pages from sitemap (up to 5) */
+    /** Sampled blog/content pages from sitemap (up to 50) */
     blogSample?: FetchResult[];
     /** Full-crawl statistics (set when --full-crawl is used) */
     crawlStats?: {
@@ -155,6 +242,8 @@ interface SiteData {
         skipped: number;
         elapsed: number;
     };
+    /** Link graph from full-site crawl */
+    linkGraph?: LinkGraph;
 }
 interface RawDataSummary {
     domain: string;
@@ -420,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.
@@ -477,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 PageCriterionScore$1 as PageCriterionScore, type PageIssue, type PageReview, type PageScoreResult, 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, scoreAllPages, scorePage, 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 };