@aexol/spectral 0.9.42 → 0.9.44

package/dist/extensions/seo/tools/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/report.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA+E9E"}

package/dist/extensions/seo/tools/report.js

@@ -0,0 +1,167 @@
+/**
+ * seo_report tool — generate formatted reports from audit results.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { errorResult, textResult } from "./helpers.js";
+export function registerReportTools(ext, config) {
+    const reportTool = {
+        name: "seo_report",
+        label: "SEO Report Generator",
+        description: "Generate a formatted SEO report from audit results. " +
+            "Accepts a FullAuditResult object (from seo_audit) and produces a Markdown, JSON, or HTML report. " +
+            "Optionally writes the report to a file in the SEO output directory (default: ~/.spectral/seo-reports/).",
+        promptSnippet: "`seo_report { auditResult, format?, outputPath? }` — generate formatted SEO report",
+        parameters: {
+            type: "object",
+            properties: {
+                auditResult: {
+                    type: "object",
+                    description: "The FullAuditResult object from seo_audit.",
+                },
+                format: {
+                    type: "string",
+                    enum: ["markdown", "json", "html"],
+                    description: "Output format. Default: 'markdown'.",
+                },
+                outputPath: {
+                    type: "string",
+                    description: "File path to write the report. If omitted, returns content only.",
+                },
+            },
+            required: ["auditResult"],
+        },
+        async execute(_toolCallId, params) {
+            const { auditResult, format, outputPath } = params;
+            try {
+                const fmt = format ?? "markdown";
+                let content;
+                switch (fmt) {
+                    case "json":
+                        content = JSON.stringify(auditResult, null, 2);
+                        break;
+                    case "html":
+                        content = generateHtmlReport(auditResult);
+                        break;
+                    case "markdown":
+                    default:
+                        content = generateMarkdownReport(auditResult);
+                        break;
+                }
+                let savedPath;
+                if (outputPath) {
+                    const fullPath = outputPath.startsWith("/")
+                        ? outputPath
+                        : join(config.outputDir, outputPath);
+                    mkdirSync(join(fullPath, ".."), { recursive: true });
+                    writeFileSync(fullPath, content, "utf-8");
+                    savedPath = fullPath;
+                }
+                const summary = `✓ Report generated (${fmt})\n` +
+                    (savedPath ? `Saved to: ${savedPath}\n` : "") +
+                    `Content length: ${content.length} chars`;
+                return textResult(summary, {
+                    format: fmt,
+                    content: content.length > 50_000 ? content.slice(0, 50_000) + "..." : content,
+                    savedPath,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(reportTool);
+}
+function generateMarkdownReport(audit) {
+    const lines = [
+        `# SEO Audit Report`,
+        ``,
+        `**URL:** ${audit.url}`,
+        `**Date:** ${audit.auditedAt}`,
+        `**Overall Score:** ${audit.overallScore}/100`,
+        ``,
+    ];
+    if (audit.technical) {
+        lines.push(`## Technical SEO`, `**Score:** ${audit.technical.score}/100`, ``);
+        lines.push(`| Category | Score |`, `|----------|-------|`);
+        for (const [cat, score] of Object.entries(audit.technical.categoryScores)) {
+            lines.push(`| ${cat} | ${score}/100 |`);
+        }
+        lines.push(``);
+        lines.push(`**HTTPS:** ${audit.technical.isHttps ? "✓" : "✗"}`);
+        lines.push(`**Mobile Optimized:** ${audit.technical.mobileOptimized ? "✓" : "✗"}`);
+        lines.push(`**robots.txt:** ${audit.technical.robotsTxt.exists ? "✓" : "✗"}`);
+        lines.push(``);
+    }
+    if (audit.content) {
+        lines.push(`## Content Quality`, `**Overall Quality:** ${audit.content.overallQuality}/100`, ``, `- Word count: ${audit.content.wordCount}`, `- Filler score: ${audit.content.fillerScore}/100`, `- AI pattern score: ${audit.content.aiPatternScore}/100`, `- Information density: ${audit.content.informationDensity}/100`, `- Repetition score: ${audit.content.repetitionScore}/100`, `- Flags: ${audit.content.flags.join(", ") || "none"}`, ``);
+    }
+    if (audit.schema) {
+        lines.push(`## Schema Markup`, `**Detected schemas:** ${audit.schema.detectedSchemas.length}`, `**Deprecated types:** ${audit.schema.deprecatedTypes.join(", ") || "none"}`, ``);
+        if (audit.schema.recommendations.length > 0) {
+            lines.push(`**Recommendations:**`);
+            for (const rec of audit.schema.recommendations) {
+                lines.push(`- ${rec}`);
+            }
+            lines.push(``);
+        }
+    }
+    if (audit.images) {
+        lines.push(`## Images`, `**Total:** ${audit.images.totalImages}`, `**Missing alt:** ${audit.images.missingAlt}`, `**Missing dimensions:** ${audit.images.missingDimensions}`, `**Modern formats:** ${audit.images.modernFormats}`, ``);
+    }
+    if (audit.preload) {
+        lines.push(`## Preload & bfcache`, `**Score:** ${audit.preload.score}/100`, `**Speculation rules:** ${audit.preload.speculationRules.inlineBlocks} inline blocks`, `**Preload hints:** ${audit.preload.preloadHints}`, ``);
+    }
+    if (audit.agentUx) {
+        lines.push(`## Agent UX`, `**Score:** ${audit.agentUx.agentUxScore}/100`, `**Real buttons:** ${audit.agentUx.html.realButtons}`, `**Real anchors:** ${audit.agentUx.html.realAnchors}`, `**div onclick widgets:** ${audit.agentUx.html.divOnclickWidgets}`, ``);
+    }
+    if (audit.allIssues.length > 0) {
+        lines.push(`## Issues (${audit.allIssues.length})`, ``);
+        const sorted = audit.allIssues.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
+        for (const issue of sorted) {
+            lines.push(`### [${issue.severity.toUpperCase()}] ${issue.title}`);
+            lines.push(`**Category:** ${issue.category}`);
+            lines.push(`**Description:** ${issue.description}`);
+            lines.push(`**Recommendation:** ${issue.recommendation}`);
+            lines.push(``);
+        }
+    }
+    return lines.join("\n");
+}
+function generateHtmlReport(audit) {
+    const md = generateMarkdownReport(audit);
+    // Simple HTML wrapper around markdown content.
+    return `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>SEO Audit Report — ${audit.url}</title>
+<style>
+body { font-family: system-ui, sans-serif; max-width: 900px; margin: 2rem auto; padding: 0 1rem; line-height: 1.6; }
+h1 { border-bottom: 2px solid #333; }
+h2 { margin-top: 2rem; color: #2563eb; }
+table { border-collapse: collapse; width: 100%; }
+td, th { border: 1px solid #ddd; padding: 0.5rem; }
+</style>
+</head>
+<body>
+<pre>${escapeHtml(md)}</pre>
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function severityRank(s) {
+    switch (s) {
+        case "critical": return 0;
+        case "high": return 1;
+        case "medium": return 2;
+        case "low": return 3;
+        default: return 4;
+    }
+}

package/dist/extensions/seo/tools/schema.d.ts

@@ -0,0 +1,7 @@
+/**
+ * seo_schema_audit and seo_schema_generate tools.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerSchemaTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/extensions/seo/tools/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/schema.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA8G9E"}

package/dist/extensions/seo/tools/schema.js

@@ -0,0 +1,105 @@
+import { auditSchema, generateSchema } from "../analyzers/schema.js";
+import { fetchPage } from "../utils/fetcher.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerSchemaTools(ext, config) {
+    const auditTool = {
+        name: "seo_schema_audit",
+        label: "SEO Schema Audit",
+        description: "Detect and validate Schema.org structured data (JSON-LD, Microdata, RDFa) on a page. " +
+            "Checks for: missing @context, deprecated types (HowTo, FAQPage, SpecialAnnouncement, etc.), " +
+            "relative URLs, invalid dates, and missing required properties. Recommends appropriate schema types " +
+            "based on page content. No external API calls.",
+        promptSnippet: "`seo_schema_audit { url }` — detect and validate Schema.org structured data",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to audit for structured data." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const result = await fetchPage(url, config);
+                if (result.error) {
+                    return errorResult(`Fetch failed: ${result.error}`);
+                }
+                const audit = auditSchema(result.content, result.finalUrl);
+                const schemaLines = audit.detectedSchemas
+                    .map((s) => `  [${s.format}] ${s.type}${s.issues.length > 0 ? ` — issues: ${s.issues.join("; ")}` : ""}`)
+                    .join("\n");
+                const summary = `✓ Schema Audit: ${result.finalUrl}\n` +
+                    `Detected Schemas: ${audit.detectedSchemas.length}\n${schemaLines || "  (none)"}\n\n` +
+                    `Deprecated Types: ${audit.deprecatedTypes.length > 0 ? audit.deprecatedTypes.join(", ") : "none"}\n` +
+                    `Missing @context: ${audit.missingContext ? "⚠️" : "✓"}\n` +
+                    `Relative URLs: ${audit.relativeUrls.length}\n` +
+                    `Invalid Dates: ${audit.invalidDates.length}\n\n` +
+                    `Recommendations:\n${audit.recommendations.map((r) => `  • ${r}`).join("\n") || "  (none)"}`;
+                return textResult(summary, { audit });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const generateTool = {
+        name: "seo_schema_generate",
+        label: "SEO Schema Generate",
+        description: "Generate ready-to-use JSON-LD structured data for common schema types: Organization, LocalBusiness, " +
+            "Article, BlogPosting, Product, BreadcrumbList, WebSite, Person, ProfilePage, DiscussionForumPosting, " +
+            "OrderAction, and Reservation. Returns valid JSON-LD with @context and absolute URLs. " +
+            "Pass type-specific fields as additional parameters.",
+        promptSnippet: "`seo_schema_generate { type, ...fields }` — generate JSON-LD for a schema type",
+        parameters: {
+            type: "object",
+            properties: {
+                type: {
+                    type: "string",
+                    enum: [
+                        "Organization", "LocalBusiness", "Article", "BlogPosting", "Product",
+                        "BreadcrumbList", "WebSite", "Person", "ProfilePage", "DiscussionForumPosting",
+                        "OrderAction", "Reservation",
+                    ],
+                    description: "The Schema.org type to generate.",
+                },
+                name: { type: "string", description: "Name (for Organization, LocalBusiness, Product, Person, etc.)." },
+                url: { type: "string", description: "URL (for Organization, WebSite, Person, etc.)." },
+                headline: { type: "string", description: "Headline (for Article, BlogPosting, DiscussionForumPosting)." },
+                author: { type: "string", description: "Author name (for Article, BlogPosting, DiscussionForumPosting)." },
+                datePublished: { type: "string", description: "Publication date (YYYY-MM-DD)." },
+                provider: { type: "string", description: "Provider name (for Reservation)." },
+                start: { type: "string", description: "Start time (for Reservation)." },
+                merchant: { type: "string", description: "Merchant name (for OrderAction)." },
+                orderUrl: { type: "string", description: "Order URL (for OrderAction)." },
+                items: {
+                    type: "array",
+                    items: { type: "object", properties: { name: { type: "string" }, url: { type: "string" } } },
+                    description: "Breadcrumb items (for BreadcrumbList).",
+                },
+                sameAs: { type: "array", items: { type: "string" }, description: "sameAs URLs (for Person, Organization)." },
+                knowsAbout: { type: "array", items: { type: "string" }, description: "knowsAbout topics (for Person, ProfilePage)." },
+            },
+            required: ["type"],
+        },
+        async execute(_toolCallId, params) {
+            try {
+                const generateParams = params;
+                const result = generateSchema(generateParams);
+                const jsonLdStr = JSON.stringify(result.jsonLd, null, 2);
+                const summary = `✓ Generated ${result.type} schema\n\n` +
+                    `Required properties: ${result.required.join(", ")}\n\n` +
+                    `<script type="application/ld+json">\n${jsonLdStr}\n</script>`;
+                return textResult(summary, {
+                    type: result.type,
+                    jsonLd: result.jsonLd,
+                    required: result.required,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(auditTool);
+    ext.registerTool(generateTool);
+}

package/dist/extensions/seo/tools/sitemap.d.ts

@@ -0,0 +1,7 @@
+/**
+ * seo_sitemap_analyze and seo_sitemap_generate tools.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerSitemapTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=sitemap.d.ts.map

package/dist/extensions/seo/tools/sitemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/sitemap.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CA0F/E"}

package/dist/extensions/seo/tools/sitemap.js

@@ -0,0 +1,85 @@
+import { analyzeSitemap, generateSitemap } from "../analyzers/sitemap.js";
+import { errorResult, textResult, truncate } from "./helpers.js";
+export function registerSitemapTools(ext, config) {
+    const analyzeTool = {
+        name: "seo_sitemap_analyze",
+        label: "SEO Sitemap Analyze",
+        description: "Fetch and analyze an XML sitemap. Parses sitemap index files and regular sitemaps. " +
+            "Reports: URL count, lastmod coverage, invalid entries, file size, child sitemaps (for index files), " +
+            "and warnings (size >50MB, >50k URLs, low lastmod coverage). No external API calls.",
+        promptSnippet: "`seo_sitemap_analyze { url }` — parse and analyze an XML sitemap",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The sitemap URL to analyze." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const result = await analyzeSitemap(url, config);
+                const summary = `✓ Sitemap Analysis: ${result.url}\n` +
+                    `Type: ${result.isSitemapIndex ? "Sitemap Index" : "URL Set"}\n` +
+                    `URL Count: ${result.urlCount}\n` +
+                    `Invalid Entries: ${result.invalidEntries}\n` +
+                    `Lastmod Coverage: ${result.lastmodCoverage}%\n` +
+                    `Size: ${result.sizeBytes} bytes\n` +
+                    (result.isSitemapIndex ? `Child Sitemaps: ${result.childSitemaps.length}\n` : "") +
+                    (result.warnings.length > 0 ? `\nWarnings:\n${result.warnings.map((w) => `  ⚠️ ${w}`).join("\n")}` : "");
+                return textResult(summary, {
+                    ...result,
+                    urls: truncate(result.urls.join("\n"), 10_000),
+                    childSitemaps: result.childSitemaps,
+                });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    const generateTool = {
+        name: "seo_sitemap_generate",
+        label: "SEO Sitemap Generate",
+        description: "Generate a valid XML sitemap from a list of URLs. Each entry can include lastmod, changefreq, " +
+            "and priority. Returns the XML string ready to save as sitemap.xml.",
+        promptSnippet: "`seo_sitemap_generate { urls: [{ loc, lastmod?, changefreq?, priority? }] }` — generate XML sitemap",
+        parameters: {
+            type: "object",
+            properties: {
+                urls: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            loc: { type: "string", description: "The URL." },
+                            lastmod: { type: "string", description: "Last modification date (YYYY-MM-DD)." },
+                            changefreq: { type: "string", description: "Change frequency (always, hourly, daily, weekly, monthly, yearly, never)." },
+                            priority: { type: "number", description: "Priority 0.0-1.0." },
+                        },
+                        required: ["loc"],
+                    },
+                    description: "List of URL entries for the sitemap.",
+                },
+            },
+            required: ["urls"],
+        },
+        async execute(_toolCallId, params) {
+            const { urls } = params;
+            try {
+                if (!urls || urls.length === 0) {
+                    return errorResult("At least one URL entry is required.");
+                }
+                const xml = generateSitemap(urls);
+                const summary = `✓ Generated sitemap with ${urls.length} URLs\n\n` +
+                    `${xml.length > 5000 ? xml.slice(0, 5000) + "\n... (truncated)" : xml}`;
+                return textResult(summary, { xml, urlCount: urls.length });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(analyzeTool);
+    ext.registerTool(generateTool);
+}

package/dist/extensions/seo/tools/technical.d.ts

@@ -0,0 +1,7 @@
+/**
+ * seo_technical_audit tool — full technical SEO audit.
+ */
+import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
+import type { SeoConfig } from "../config.js";
+export declare function registerTechnicalTools(ext: ExtensionAPI, config: SeoConfig): void;
+//# sourceMappingURL=technical.d.ts.map

package/dist/extensions/seo/tools/technical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technical.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/tools/technical.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAqDjF"}

package/dist/extensions/seo/tools/technical.js

@@ -0,0 +1,62 @@
+import { auditTechnical } from "../analyzers/technical.js";
+import { fetchPage } from "../utils/fetcher.js";
+import { parsePage } from "../utils/parser.js";
+import { errorResult, textResult } from "./helpers.js";
+export function registerTechnicalTools(ext, config) {
+    const technicalTool = {
+        name: "seo_technical_audit",
+        label: "SEO Technical Audit",
+        description: "Run a comprehensive technical SEO audit covering: crawlability (robots.txt, sitemap reference), " +
+            "indexability (canonical, noindex, H1 count), security (HTTPS, security headers), URL structure " +
+            "(length, redirect chains, case), mobile optimization (viewport), and AI crawler management " +
+            "(GPTBot, ClaudeBot, Google-Extended directives). Returns a 0-100 score with categorized issues " +
+            "and priority recommendations. No external API keys required.",
+        promptSnippet: "`seo_technical_audit { url }` — audit technical SEO (crawlability, security, mobile, AI crawlers)",
+        promptGuidelines: [
+            "When the user asks about SEO, search optimization, page audits, schema markup, sitemaps, or technical SEO for any website or URL, use the seo_* tools. Start with seo_audit for comprehensive analysis or use targeted tools like seo_technical_audit for specific concerns. These are offline-first and require no API keys.",
+        ],
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to audit." },
+            },
+            required: ["url"],
+        },
+        async execute(_toolCallId, params) {
+            const { url } = params;
+            try {
+                const fetchResult = await fetchPage(url, config);
+                const pageData = parsePage(fetchResult.content, fetchResult.finalUrl);
+                const result = await auditTechnical(url, config, pageData, fetchResult);
+                const issueLines = result.issues
+                    .sort((a, b) => severityRank(a.severity) - severityRank(b.severity))
+                    .map((i) => `  [${i.severity.toUpperCase()}] ${i.category}: ${i.title}`)
+                    .join("\n");
+                const summary = `✓ Technical Audit: ${result.url}\n` +
+                    `Overall Score: ${result.score}/100\n\n` +
+                    `Category Scores:\n${Object.entries(result.categoryScores)
+                        .map(([cat, score]) => `  ${cat}: ${score}/100`)
+                        .join("\n")}\n\n` +
+                    `HTTPS: ${result.isHttps ? "✓" : "✗"}\n` +
+                    `Mobile Optimized: ${result.mobileOptimized ? "✓" : "✗"}\n` +
+                    `robots.txt: ${result.robotsTxt.exists ? "✓" : "✗"}\n` +
+                    `AI Crawler Rules: ${result.robotsTxt.aiCrawlerRules.length}\n\n` +
+                    `Issues (${result.issues.length}):\n${issueLines || "  (none)"}`;
+                return textResult(summary, { result });
+            }
+            catch (err) {
+                return errorResult(err instanceof Error ? err.message : String(err));
+            }
+        },
+    };
+    ext.registerTool(technicalTool);
+}
+function severityRank(s) {
+    switch (s) {
+        case "critical": return 0;
+        case "high": return 1;
+        case "medium": return 2;
+        case "low": return 3;
+        default: return 4;
+    }
+}