pagetrace 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,232 @@
+import { HTMLElement } from 'node-html-parser';
+
+type Severity = 'error' | 'warn' | 'info';
+/** A single structured-data entity found on a page. */
+interface JsonLdEntity {
+    type: string;
+    id?: string;
+    /** Sorted list of top-level property names present on the entity. */
+    properties: string[];
+}
+/** The normalized SEO/AEO surface of one page. */
+interface PageFingerprint {
+    route: string;
+    title: string | null;
+    description: string | null;
+    canonical: string | null;
+    /** Content of <meta name="robots">, lowercased. */
+    robots: string | null;
+    og: Record<string, string>;
+    twitter: Record<string, string>;
+    /** hreflang value -> href */
+    hreflang: Record<string, string>;
+    h1: string[];
+    /** Heading tag sequence in document order, e.g. ["h1","h2","h2","h3"]. */
+    headingOutline: string[];
+    jsonLd: JsonLdEntity[];
+    wordCount: number;
+    images: {
+        total: number;
+        missingAlt: number;
+    };
+    /** Whether the page exposes an answer-shaped opening paragraph (AEO signal). */
+    leadAnswerWords: number;
+    /** Content of <meta name="generator">, used for platform detection. */
+    generator: string | null;
+}
+/** Site-wide signals that live outside any single page. */
+interface SiteFingerprint {
+    /**
+     * The origin this snapshot was crawled from, e.g. "https://example.com".
+     * Absent for a filesystem crawl and for lockfiles written before 0.2.0.
+     */
+    origin?: string | null;
+    robotsTxt: {
+        present: boolean;
+        /** agent name -> whether the root path is crawlable */
+        aiAgents: Record<string, 'allowed' | 'disallowed'>;
+        sitemaps: string[];
+    } | null;
+    llmsTxt: {
+        present: boolean;
+        /** H2 section titles, used to detect silent truncation. */
+        sections: string[];
+        bytes: number;
+    } | null;
+}
+interface Snapshot {
+    schemaVersion: 1;
+    createdAt: string;
+    site: SiteFingerprint;
+    pages: Record<string, PageFingerprint>;
+}
+type Platform = 'wordpress' | 'nextjs' | 'shopify' | 'webflow' | 'wix' | 'squarespace' | 'drupal' | 'unknown';
+interface Finding {
+    /** Stable machine code, e.g. "canonical.removed". Integrations key on this. */
+    code: string;
+    severity: Severity;
+    route: string | null;
+    message: string;
+    before?: unknown;
+    after?: unknown;
+    /** Why this matters, for audit output. */
+    detail?: string;
+    /** How to fix it, platform-specific where known. */
+    fix?: string;
+}
+/** One issue rolled up across every route it affects. */
+interface Aggregate {
+    code: string;
+    severity: Severity;
+    count: number;
+    routes: string[];
+    message: string;
+    detail?: string;
+    fix?: string;
+}
+interface Config {
+    /** Per-code severity overrides. Set to "off" to silence a rule. */
+    severity?: Record<string, Severity | 'off'>;
+    /** Routes to skip entirely (exact match or trailing-* prefix). */
+    ignoreRoutes?: string[];
+    /** Extra AI user agents to check in robots.txt. */
+    aiAgents?: string[];
+    /** Minimum word count before a page is flagged as thin. */
+    minWordCount?: number;
+    /**
+     * The site's own origin, e.g. "https://example.com". Lets a --dir crawl detect
+     * canonicals pointing at another host; an origin crawl infers it.
+     */
+    siteUrl?: string;
+}
+
+/**
+ * Rules that hold regardless of history. These overlap with what any auditor
+ * reports; the diff engine in `diff.ts` is what catches regressions.
+ */
+declare function auditPage(page: PageFingerprint, config?: Config): Finding[];
+declare function auditSite(snapshot: Snapshot): Finding[];
+/**
+ * Rules that only exist when you look at the whole site at once. These are the
+ * findings that matter most on a large CMS site, where the defects come from
+ * templates rather than individual pages.
+ */
+declare function auditCrossPage(snapshot: Snapshot): Finding[];
+/**
+ * hreflang is the rule set most worth automating: Google requires the
+ * annotations to be reciprocal, and a one-sided set is silently ignored rather
+ * than reported anywhere. You cannot see this from a single page, which is why
+ * it lives here rather than in auditPage.
+ */
+declare function auditHreflang(snapshot: Snapshot): Finding[];
+declare function auditSnapshot(snapshot: Snapshot, config?: Config): Finding[];
+
+declare function diffPage(before: PageFingerprint, after: PageFingerprint): Finding[];
+declare function diffSite(before: Snapshot['site'], after: Snapshot['site']): Finding[];
+declare function diffSnapshots(before: Snapshot, after: Snapshot): Finding[];
+
+declare function extractJsonLd(root: HTMLElement): JsonLdEntity[];
+declare function extractPage(html: string, route: string): PageFingerprint;
+/** Parse robots.txt into per-agent crawlability of the site root. */
+declare function extractRobotsTxt(body: string, agents: string[]): {
+    present: boolean;
+    aiAgents: Record<string, "allowed" | "disallowed">;
+    sitemaps: string[];
+};
+/** Parse llms.txt, capturing section headings so truncation is detectable. */
+declare function extractLlmsTxt(body: string): {
+    present: boolean;
+    sections: string[];
+    bytes: number;
+};
+/** Pull <loc> entries out of a sitemap or sitemap index. */
+declare function extractSitemapUrls(xml: string): string[];
+
+interface Guidance {
+    /** Why the issue costs you traffic or citations. */
+    why: string;
+    /** Generic remedy. */
+    fix: string;
+    /** Platform-specific remedy, used when the platform is detected. */
+    byPlatform?: Partial<Record<Platform, string>>;
+}
+/**
+ * Explanations attached to findings in audit output. Diff output stays terse —
+ * you already know what a canonical is when you are reviewing a regression.
+ * An audit handed to a client or a content team needs the reasoning.
+ */
+declare const GUIDANCE: Record<string, Guidance>;
+/** Detect the publishing platform from generator meta and URL shape. */
+declare function detectPlatform(generators: (string | null)[], urls?: string[]): Platform;
+/** Attach why/fix text to a finding, preferring platform-specific advice. */
+declare function withGuidance<T extends {
+    code: string;
+}>(finding: T, platform?: Platform): T & {
+    detail?: string;
+    fix?: string;
+};
+
+/** Apply user severity overrides and drop anything switched off. */
+declare function applyConfig(findings: Finding[], config?: Config): Finding[];
+declare function summarize(findings: Finding[]): {
+    error: number;
+    warn: number;
+    info: number;
+};
+declare function shouldFail(findings: Finding[], failOn: Severity): boolean;
+declare function formatPretty(findings: Finding[]): string;
+declare function formatJson(findings: Finding[]): string;
+/** Markdown table, sized for a PR comment. */
+declare function formatMarkdown(findings: Finding[]): string;
+/** GitHub Actions workflow-command annotations. */
+declare function formatGithub(findings: Finding[]): string;
+/**
+ * Roll findings up by issue rather than by page. On a large CMS site the same
+ * template defect produces hundreds of identical findings; the useful unit is
+ * "canonical missing on 43 pages", not 43 separate lines.
+ */
+declare function aggregate(findings: Finding[]): Aggregate[];
+interface AuditMeta {
+    target: string;
+    platform: Platform;
+    pageCount: number;
+    generatedAt: string;
+}
+declare function formatAuditPretty(groups: Aggregate[], meta: AuditMeta): string;
+declare function formatAuditMarkdown(groups: Aggregate[], meta: AuditMeta): string;
+/** Self-contained HTML report, suitable for handing to a client. */
+declare function formatAuditHtml(groups: Aggregate[], meta: AuditMeta): string;
+
+/**
+ * Required and recommended properties for the Schema.org types Google supports
+ * as rich results. Sourced from Google Search Central's structured data
+ * reference. Deliberately a plain data table so it can be updated without
+ * touching the engine, and so consumers can extend it.
+ */
+interface RichResultRule {
+    required: string[];
+    recommended: string[];
+    /** Groups where at least one member must be present. */
+    oneOf?: string[][];
+}
+declare const RICH_RESULT_RULES: Record<string, RichResultRule>;
+/** AI crawler user agents checked against robots.txt by default. */
+declare const DEFAULT_AI_AGENTS: string[];
+
+declare function routeFromFilePath(root: string, filePath: string): string;
+declare function routeFromUrl(url: string): string;
+declare function shouldIgnore(route: string, patterns?: string[]): boolean;
+/** Build a snapshot from a directory of pre-rendered HTML (next export, dist, out). */
+declare function snapshotFromDir(dir: string, config?: Config): Promise<Snapshot>;
+interface CrawlOptions extends Config {
+    /** Cap the number of pages fetched. */
+    limit?: number;
+    /** Parallel requests. */
+    concurrency?: number;
+    /** Per-request timeout in milliseconds. */
+    timeout?: number;
+}
+/** Build a snapshot by fetching a live origin, discovering routes via sitemap. */
+declare function snapshotFromOrigin(origin: string, options?: CrawlOptions): Promise<Snapshot>;
+
+export { type Aggregate, type AuditMeta, type Config, DEFAULT_AI_AGENTS, type Finding, GUIDANCE, type Guidance, type JsonLdEntity, type PageFingerprint, type Platform, RICH_RESULT_RULES, type Severity, type SiteFingerprint, type Snapshot, aggregate, applyConfig, auditCrossPage, auditHreflang, auditPage, auditSite, auditSnapshot, detectPlatform, diffPage, diffSite, diffSnapshots, extractJsonLd, extractLlmsTxt, extractPage, extractRobotsTxt, extractSitemapUrls, formatAuditHtml, formatAuditMarkdown, formatAuditPretty, formatGithub, formatJson, formatMarkdown, formatPretty, routeFromFilePath, routeFromUrl, shouldFail, shouldIgnore, snapshotFromDir, snapshotFromOrigin, summarize, withGuidance };