@aexol/spectral 0.9.42 → 0.9.44

package/dist/extensions/seo/types.d.ts

@@ -0,0 +1,445 @@
+/**
+ * Shared types for the SEO extension.
+ *
+ * All types are plain data structures (no class hierarchies) so they can be
+ * serialised to JSON and returned as tool `details` without transformation.
+ */
+/** A single HTTP redirect hop in a fetch redirect chain. */
+export interface RedirectHop {
+    url: string;
+    status: number;
+}
+/** Result of fetching a URL. */
+export interface FetchResult {
+    url: string;
+    finalUrl: string;
+    statusCode: number;
+    statusText: string;
+    headers: Record<string, string>;
+    content: string;
+    redirectChain: RedirectHop[];
+    contentLengthBytes: number;
+    fetchedAt: string;
+    error?: string;
+}
+/** A parsed heading element. */
+export interface HeadingInfo {
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+    /** True if the heading looks auto-generated or suspicious (e.g. empty, "Click here"). */
+    suspicious?: boolean;
+}
+/** A parsed image element. */
+export interface ImageInfo {
+    src: string;
+    alt: string;
+    width?: string;
+    height?: string;
+    loading?: string;
+    /** Detected lazy-loading method: "native", "dataSrc", "dataLazy", "none". */
+    lazyMethod: "native" | "dataSrc" | "dataLazy" | "none";
+    fetchpriority?: string;
+}
+/** A parsed link element. */
+export interface LinkInfo {
+    href: string;
+    text: string;
+    rel: string;
+    /** "internal" or "external" relative to baseUrl. */
+    type: "internal" | "external";
+    nofollow: boolean;
+}
+/** A detected JSON-LD schema block. */
+export interface SchemaBlock {
+    type: string;
+    format: "json-ld" | "microdata" | "rdfa";
+    raw: string;
+    parsed?: unknown;
+    issues: string[];
+}
+/** Open Graph tag. */
+export interface OpenGraphTag {
+    property: string;
+    content: string;
+}
+/** Twitter Card tag. */
+export interface TwitterTag {
+    name: string;
+    content: string;
+}
+/** Hreflang entry. */
+export interface HreflangEntry {
+    href: string;
+    hreflang: string;
+}
+/** Parsed on-page SEO data extracted from HTML. */
+export interface PageData {
+    url: string;
+    baseUrl: string;
+    title: string | null;
+    titleLength: number;
+    metaDescription: string | null;
+    metaDescriptionLength: number;
+    metaRobots: string | null;
+    canonical: string | null;
+    ogTags: OpenGraphTag[];
+    twitterTags: TwitterTag[];
+    headings: HeadingInfo[];
+    h1Count: number;
+    h2Count: number;
+    h3Count: number;
+    images: ImageInfo[];
+    links: LinkInfo[];
+    internalLinkCount: number;
+    externalLinkCount: number;
+    schemaBlocks: SchemaBlock[];
+    hreflang: HreflangEntry[];
+    wordCount: number;
+    language: string | null;
+    viewport: string | null;
+    charset: string | null;
+}
+/** A single audit issue with severity. */
+export interface AuditIssue {
+    category: string;
+    severity: "critical" | "high" | "medium" | "low";
+    title: string;
+    description: string;
+    recommendation: string;
+}
+/** Result of a technical SEO audit. */
+export interface TechnicalAuditResult {
+    url: string;
+    score: number;
+    issues: AuditIssue[];
+    categoryScores: Record<string, number>;
+    robotsTxt: {
+        exists: boolean;
+        sitemapDeclared: boolean;
+        aiCrawlerRules: string[];
+        content?: string;
+    };
+    securityHeaders: Record<string, string | null>;
+    isHttps: boolean;
+    mobileOptimized: boolean;
+}
+/** Result of content quality analysis. */
+export interface ContentQualityResult {
+    url?: string;
+    wordCount: number;
+    tokens: number;
+    uniqueTokens: number;
+    fillerScore: number;
+    aiPatternScore: number;
+    informationDensity: number;
+    repetitionScore: number;
+    overallQuality: number;
+    flags: string[];
+    fillerMatches: string[];
+    aiPatternMatches: string[];
+}
+/** Result of schema audit. */
+export interface SchemaAuditResult {
+    url?: string;
+    detectedSchemas: SchemaBlock[];
+    deprecatedTypes: string[];
+    missingContext: boolean;
+    relativeUrls: string[];
+    invalidDates: string[];
+    recommendations: string[];
+}
+/** Result of sitemap analysis. */
+export interface SitemapAnalysisResult {
+    url: string;
+    urlCount: number;
+    urls: string[];
+    lastmodCoverage: number;
+    invalidEntries: number;
+    sizeBytes: number;
+    isSitemapIndex: boolean;
+    childSitemaps: string[];
+    warnings: string[];
+}
+/** Result of image audit. */
+export interface ImageAuditResult {
+    url: string;
+    totalImages: number;
+    missingAlt: number;
+    missingDimensions: number;
+    lazyLoading: {
+        native: number;
+        dataSrc: number;
+        dataLazy: number;
+        none: number;
+    };
+    modernFormats: number;
+    oversized: string[];
+    images: ImageInfo[];
+}
+/** Result of preload / speculation rules audit. */
+export interface PreloadAuditResult {
+    url: string;
+    speculationRules: {
+        inlineBlocks: number;
+        headerPresent: boolean;
+        actions: string[];
+    };
+    preloadHints: number;
+    prerenderLinks: number;
+    bfcacheSignals: {
+        cacheControlNoStore: boolean;
+        unloadListener: boolean;
+        beforeunloadListener: boolean;
+    };
+    lcpResourceHints: {
+        preloadLcpCandidate: boolean;
+        fetchpriorityHigh: number;
+    };
+    score: number;
+    recommendations: string[];
+}
+/** Result of agent UX audit. */
+export interface AgentUxAuditResult {
+    url: string;
+    agentUxScore: number;
+    html: {
+        realButtons: number;
+        realAnchors: number;
+        divOnclickWidgets: number;
+        semanticLandmarks: number;
+        inputsTotal: number;
+        inputsMissingLabel: number;
+    };
+    accessibilityTree: {
+        totalNodes: number;
+        interactiveNodes: number;
+        unnamedInteractive: number;
+        roleGenericRatio: number;
+    };
+    opportunities: string[];
+}
+/** A single page's parasite-SEO audit data. */
+export interface ParasitePageAudit {
+    url: string;
+    thirdPartyHits: number;
+    commerceHits: number;
+    affiliateLinkHits: number;
+}
+/** Result of parasite risk scan. */
+export interface ParasiteRiskResult {
+    host: string;
+    totalPages: number;
+    sections: Array<{
+        section: string;
+        pageCount: number;
+        thirdPartyHitsPerPage: number;
+        commerceHitsPerPage: number;
+        affiliateLinkHitsPerPage: number;
+        flags: string[];
+        risk: "high" | "medium" | "low";
+    }>;
+}
+/** A drift baseline snapshot. */
+export interface DriftBaseline {
+    id: number;
+    url: string;
+    urlHash: string;
+    timestamp: string;
+    title: string | null;
+    metaDescription: string | null;
+    canonical: string | null;
+    robots: string | null;
+    h1: string | null;
+    h2Json: string;
+    h3Json: string;
+    schemaJson: string;
+    ogJson: string;
+    htmlHash: string;
+    schemaHash: string;
+    statusCode: number;
+}
+/** Result of comparing current state against a baseline. */
+export interface DriftCompareResult {
+    url: string;
+    baselineId: number;
+    baselineTimestamp: string;
+    comparedAt: string;
+    changedFields: string[];
+    details: Record<string, {
+        before: unknown;
+        after: unknown;
+    }>;
+    severity: "none" | "low" | "medium" | "high";
+}
+/** Full audit result combining all sub-audits. */
+export interface FullAuditResult {
+    url: string;
+    auditedAt: string;
+    overallScore: number;
+    technical?: TechnicalAuditResult;
+    content?: ContentQualityResult;
+    schema?: SchemaAuditResult;
+    images?: ImageAuditResult;
+    preload?: PreloadAuditResult;
+    agentUx?: AgentUxAuditResult;
+    sitemap?: SitemapAnalysisResult;
+    allIssues: AuditIssue[];
+    summary: string;
+}
+export interface CrawlConfig {
+    maxPages: number;
+    maxDepth: number;
+    concurrency: number;
+    respectRobotsTxt: boolean;
+    crawlDelayMs: number;
+    includeExternal: boolean;
+}
+export interface CrawledPage {
+    url: string;
+    depth: number;
+    statusCode: number;
+    fetchResult: FetchResult;
+    pageData: PageData;
+    linksFound: string[];
+    crawlDuration: number;
+    error?: string;
+}
+export interface BrokenLink {
+    sourcePage: string;
+    targetUrl: string;
+    statusCode: number;
+    linkText: string;
+}
+export interface DuplicateGroup {
+    type: "title" | "description" | "h1";
+    value: string;
+    pageUrls: string[];
+}
+export interface LinkGraphNode {
+    url: string;
+    internalInlinks: number;
+    internalOutlinks: number;
+    externalOutlinks: number;
+    pageRank?: number;
+    depth: number;
+    statusCode: number;
+}
+export interface CrawlResult {
+    baseUrl: string;
+    pagesCrawled: number;
+    totalPagesFound: number;
+    maxDepthReached: number;
+    brokenLinks: BrokenLink[];
+    duplicateGroups: DuplicateGroup[];
+    orphanPages: string[];
+    pages: CrawledPage[];
+    linkGraph: LinkGraphNode[];
+    errors: string[];
+}
+export interface KeywordInfo {
+    keyword: string;
+    count: number;
+    density: number;
+    tfidf: number;
+    variants: string[];
+}
+export interface KeywordAnalysisResult {
+    url: string;
+    totalWords: number;
+    keywords: KeywordInfo[];
+    topNgrams: Array<{
+        ngram: string;
+        count: number;
+    }>;
+    searchIntent: "informational" | "commercial" | "transactional" | "mixed";
+    intentConfidence: number;
+    keywordStuffingFlags: string[];
+}
+export interface ReadabilityResult {
+    url: string;
+    fleschKincaid: number;
+    fleschReadingEase: number;
+    smog: number;
+    ari: number;
+    colemanLiau: number;
+    gradeAverage: number;
+    sentenceCount: number;
+    syllableCount: number;
+    complexWordCount: number;
+}
+export interface ContentOptimizationResult {
+    url: string;
+    titleScore: number;
+    descriptionScore: number;
+    headingStructureScore: number;
+    contentLengthScore: number;
+    overallScore: number;
+    issues: Array<{
+        category: string;
+        severity: "critical" | "high" | "medium" | "low";
+        issue: string;
+        recommendation: string;
+    }>;
+}
+export interface PerformanceResult {
+    url: string;
+    lcp: {
+        value: number;
+        rating: "good" | "needs-improvement" | "poor";
+        element?: string;
+    };
+    cls: {
+        value: number;
+        rating: "good" | "needs-improvement" | "poor";
+    };
+    tbt: {
+        value: number;
+        rating: "good" | "needs-improvement" | "poor";
+    };
+    fcp: number;
+    ttfb: number;
+    score: number;
+}
+export interface PageWeightResult {
+    url: string;
+    totalKb: number;
+    htmlKb: number;
+    cssKb: number;
+    jsKb: number;
+    imageKb: number;
+    fontKb: number;
+    otherKb: number;
+    resourceCount: number;
+    topHeavyResources: Array<{
+        url: string;
+        sizeKb: number;
+        type: string;
+    }>;
+}
+export interface RenderBlockingResult {
+    url: string;
+    blockingCss: Array<{
+        href: string;
+        sizeEstimate: number;
+    }>;
+    blockingJs: Array<{
+        src: string;
+        sizeEstimate: number;
+    }>;
+    totalBlockingUrls: number;
+    recommendations: string[];
+}
+export interface FontAuditResult {
+    url: string;
+    fontsFound: Array<{
+        family: string;
+        source: string;
+        hasDisplay: boolean;
+        isSubset: boolean;
+        format: string;
+    }>;
+    hasFontDisplay: boolean;
+    recommendations: string[];
+    score: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/extensions/seo/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/extensions/seo/types.ts"],"names":[],"mappings":"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"}

package/dist/extensions/seo/types.js

@@ -0,0 +1,7 @@
+/**
+ * Shared types for the SEO extension.
+ *
+ * All types are plain data structures (no class hierarchies) so they can be
+ * serialised to JSON and returned as tool `details` without transformation.
+ */
+export {};

package/dist/extensions/seo/utils/fetcher.d.ts

@@ -0,0 +1,28 @@
+/**
+ * HTTP fetcher with redirect tracking, timeout, and charset detection.
+ *
+ * Ported from the Python `fetch_page.py` in claude-seo. Uses Node's native
+ * fetch (Node 20+) with manual redirect handling to capture the full chain.
+ */
+import type { SeoConfig } from "../config.js";
+import type { FetchResult } from "../types.js";
+export interface FetchOptions {
+    userAgent?: "default" | "googlebot" | string;
+    timeout?: number;
+    followRedirects?: boolean;
+    maxRedirects?: number;
+    /** Extra headers to send. */
+    headers?: Record<string, string>;
+    /** Whether to run SSRF protection (DNS-based private IP blocking). */
+    ssrfProtection?: boolean;
+}
+/**
+ * Fetch a URL with full redirect-chain tracking.
+ *
+ * Returns a FetchResult containing the final URL, status, headers, content,
+ * and the complete redirect chain.
+ */
+export declare function fetchPage(url: string, config: SeoConfig, opts?: FetchOptions): Promise<FetchResult>;
+/** Fetch a robots.txt file for a given URL's origin. */
+export declare function fetchRobotsTxt(pageUrl: string, config: SeoConfig, opts?: FetchOptions): Promise<FetchResult>;
+//# sourceMappingURL=fetcher.d.ts.map

package/dist/extensions/seo/utils/fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetcher.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/utils/fetcher.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,aAAa,CAAC;AAG5D,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAwBD;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,WAAW,CAAC,CA4FtB;AAED,wDAAwD;AACxD,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,WAAW,CAAC,CAItB"}

package/dist/extensions/seo/utils/fetcher.js

@@ -0,0 +1,118 @@
+import { UrlSafetyError, validateUrl } from "./url-safety.js";
+/** Decode a fetch response body respecting charset from Content-Type header. */
+async function decodeBody(res) {
+    const contentType = res.headers.get("content-type") ?? "";
+    const buffer = await res.arrayBuffer();
+    const decoder = new TextDecoder(detectCharset(contentType) ?? "utf-8");
+    return decoder.decode(buffer);
+}
+function detectCharset(contentType) {
+    const match = /charset=([^\s;]+)/i.exec(contentType);
+    if (match)
+        return match[1].toLowerCase().trim();
+    return undefined;
+}
+function headersToRecord(headers) {
+    const rec = {};
+    headers.forEach((value, key) => {
+        rec[key] = value;
+    });
+    return rec;
+}
+/**
+ * Fetch a URL with full redirect-chain tracking.
+ *
+ * Returns a FetchResult containing the final URL, status, headers, content,
+ * and the complete redirect chain.
+ */
+export async function fetchPage(url, config, opts = {}) {
+    const timeout = opts.timeout ?? config.timeout;
+    const followRedirects = opts.followRedirects ?? config.followRedirects;
+    const maxRedirects = opts.maxRedirects ?? config.maxRedirects;
+    const ssrfProtection = opts.ssrfProtection ?? config.ssrfProtection;
+    const validated = await validateUrl(url, { ssrfProtection });
+    const ua = opts.userAgent === "googlebot"
+        ? config.googlebotUserAgent
+        : opts.userAgent === "default" || !opts.userAgent
+            ? config.userAgent
+            : opts.userAgent;
+    const redirectChain = [];
+    let currentUrl = validated.href;
+    let lastResponse = null;
+    let lastError;
+    for (let i = 0; i <= maxRedirects; i++) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const res = await fetch(currentUrl, {
+                redirect: "manual",
+                signal: controller.signal,
+                headers: {
+                    "User-Agent": ua,
+                    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                    "Accept-Language": "en-US,en;q=0.9",
+                    ...opts.headers,
+                },
+            });
+            clearTimeout(timeoutId);
+            // Handle redirects manually to capture the full chain.
+            if (res.status >= 300 && res.status < 400 && followRedirects) {
+                const location = res.headers.get("location");
+                if (location) {
+                    redirectChain.push({ url: currentUrl, status: res.status });
+                    currentUrl = new URL(location, currentUrl).href;
+                    // Validate redirect target for SSRF.
+                    await validateUrl(currentUrl, { ssrfProtection, resolveDns: false });
+                    continue;
+                }
+            }
+            lastResponse = res;
+            break;
+        }
+        catch (err) {
+            clearTimeout(timeoutId);
+            if (err instanceof UrlSafetyError)
+                throw err;
+            lastError = err instanceof Error ? err.message : String(err);
+            break;
+        }
+    }
+    if (!lastResponse) {
+        return {
+            url: validated.href,
+            finalUrl: currentUrl,
+            statusCode: 0,
+            statusText: "Error",
+            headers: {},
+            content: "",
+            redirectChain,
+            contentLengthBytes: 0,
+            fetchedAt: new Date().toISOString(),
+            error: lastError ?? "Unknown fetch error",
+        };
+    }
+    let content = "";
+    try {
+        content = await decodeBody(lastResponse);
+    }
+    catch {
+        content = "";
+    }
+    return {
+        url: validated.href,
+        finalUrl: currentUrl,
+        statusCode: lastResponse.status,
+        statusText: lastResponse.statusText,
+        headers: headersToRecord(lastResponse.headers),
+        content,
+        redirectChain,
+        contentLengthBytes: Buffer.byteLength(content, "utf-8"),
+        fetchedAt: new Date().toISOString(),
+    };
+}
+/** Fetch a robots.txt file for a given URL's origin. */
+export async function fetchRobotsTxt(pageUrl, config, opts = {}) {
+    const validated = await validateUrl(pageUrl, { ssrfProtection: opts.ssrfProtection ?? config.ssrfProtection });
+    const robotsUrl = `${validated.protocol}//${validated.hostname}/robots.txt`;
+    return fetchPage(robotsUrl, config, opts);
+}

package/dist/extensions/seo/utils/parser.d.ts

@@ -0,0 +1,8 @@
+import type { PageData } from "../types.js";
+/** Parse a full PageData object from HTML. */
+export declare function parsePage(html: string, url?: string, baseUrl?: string): PageData;
+/** Extract the visible text content from HTML body. */
+export declare function extractText(html: string): string;
+/** Extract raw JSON-LD blocks as parsed objects. */
+export declare function extractJsonLd(html: string): unknown[];
+//# sourceMappingURL=parser.d.ts.map

package/dist/extensions/seo/utils/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/utils/parser.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAMV,QAAQ,EAGT,MAAM,aAAa,CAAC;AAgGrB,8CAA8C;AAC9C,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,CA4IhF;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAerD"}