@aexol/spectral 0.9.126 → 0.9.128

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

@@ -35,20 +35,86 @@ const REQUIRED_PROPERTIES = {
     VideoObject: ["name", "uploadDate"],
     JobPosting: ["title", "description", "hiringOrganization"],
     Course: ["name", "provider"],
+    HowTo: ["name", "step"],
+    ItemList: ["itemListElement"],
+    Recipe: ["name", "recipeIngredient", "recipeInstructions"],
+    FAQPage: ["mainEntity"],
+    SoftwareApplication: ["name", "operatingSystem"],
+    WebApplication: ["name", "operatingSystem"],
+    Person: ["name"],
+    WebSite: ["name", "url"],
 };
+/** Normalize a `@type` value (string or array) into a single type name,
+ *  stripping a leading `https://schema.org/` prefix when present. */
+function normalizeType(rawType) {
+    if (typeof rawType === "string") {
+        return rawType.replace("https://schema.org/", "");
+    }
+    if (Array.isArray(rawType) && rawType.length > 0) {
+        const first = rawType[0];
+        return typeof first === "string" ? first.replace("https://schema.org/", "") : "Unknown";
+    }
+    return "Unknown";
+}
+/** Build a map of `@id` -> entity from a list of JSON-LD items. */
+function buildEntityMap(items) {
+    const map = new Map();
+    for (const item of items) {
+        if (!item || typeof item !== "object")
+            continue;
+        const obj = item;
+        const id = obj["@id"];
+        if (typeof id === "string" && id.length > 0 && !map.has(id)) {
+            map.set(id, item);
+        }
+    }
+    return map;
+}
+/** Resolve `@id` references recursively. A bare reference (an object containing
+ *  only `@id`, or `@id` plus one other key) is replaced by the referenced
+ *  entity. A `visited` Set prevents infinite loops on cyclic references. */
+function resolveReferences(value, entityMap, visited) {
+    if (!value || typeof value !== "object")
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((v) => resolveReferences(v, entityMap, visited));
+    }
+    const obj = value;
+    const id = obj["@id"];
+    if (typeof id === "string") {
+        const keys = Object.keys(obj);
+        const isBareRef = keys.length === 1 || keys.length === 2;
+        if (isBareRef && entityMap.has(id) && !visited.has(id)) {
+            visited.add(id);
+            const resolved = resolveReferences(entityMap.get(id), entityMap, visited);
+            visited.delete(id);
+            return resolved;
+        }
+    }
+    // Recursively resolve nested references on a shallow copy.
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        out[k] = resolveReferences(v, entityMap, visited);
+    }
+    return out;
+}
 /** Validate a parsed JSON-LD object and return issues. */
-function validateSchemaItem(item) {
+function validateSchemaItem(item, entityMap) {
     if (!item || typeof item !== "object") {
         return { type: "Unknown", issues: ["Invalid schema object"] };
     }
-    const obj = item;
+    let obj;
+    if (entityMap) {
+        const resolved = resolveReferences(item, entityMap, new Set());
+        obj = (resolved && typeof resolved === "object"
+            ? resolved
+            : item);
+    }
+    else {
+        obj = item;
+    }
     const rawType = obj["@type"];
-    // Handle @type arrays (e.g. ["Article", "NewsArticle"]) and full URLs.
-    const type = typeof rawType === "string"
-        ? rawType.replace("https://schema.org/", "")
-        : Array.isArray(rawType) && rawType.length > 0
-            ? rawType[0].replace("https://schema.org/", "")
-            : "Unknown";
+    const type = normalizeType(rawType);
     const issues = [];
     if (!obj["@context"]) {
         issues.push("Missing @context");
@@ -64,7 +130,7 @@ function validateSchemaItem(item) {
     }
     // Check for relative URLs.
     const jsonStr = JSON.stringify(obj);
-    if (jsonStr.includes('"url":"/') || jsonStr.includes('"url": "/')) {
+    if (/("url"\s*:\s*"\/)[^/]/.test(jsonStr)) {
         issues.push("Contains relative URL — should be absolute");
     }
     // Check date formats.
@@ -85,11 +151,25 @@ export function auditSchema(html, url) {
     const deprecatedTypes = [];
     const relativeUrls = [];
     const invalidDates = [];
+    const duplicateEntities = [];
     let missingContext = false;
     // Re-validate with deeper checks using parsed JSON-LD.
     const jsonLdItems = extractJsonLd(html);
+    const entityMap = buildEntityMap(jsonLdItems);
+    const seenIds = new Set();
     for (const item of jsonLdItems) {
-        const { type, issues } = validateSchemaItem(item);
+        if (item && typeof item === "object") {
+            const id = item["@id"];
+            if (typeof id === "string" && id.length > 0) {
+                if (seenIds.has(id)) {
+                    duplicateEntities.push(id);
+                }
+                else {
+                    seenIds.add(id);
+                }
+            }
+        }
+        const { type, issues } = validateSchemaItem(item, entityMap);
         if (DEPRECATED_TYPES.has(type)) {
             deprecatedTypes.push(type);
         }
@@ -115,6 +195,9 @@ export function auditSchema(html, url) {
     if (detectedSchemas.length === 0) {
         recommendations.push("No structured data found. Add JSON-LD markup for rich result eligibility.");
     }
+    if (duplicateEntities.length > 0) {
+        recommendations.push(`Duplicate @id entities detected: ${duplicateEntities.length}. Deduplicate entities referenced by @id.`);
+    }
     // Recommend types based on page content.
     const hasArticle = pageData.wordCount > 300 && (pageData.title ?? "").length > 0;
     if (hasArticle && !detectedSchemas.some((s) => ["Article", "BlogPosting", "NewsArticle"].includes(s.type))) {
@@ -123,8 +206,14 @@ export function auditSchema(html, url) {
     if (detectedSchemas.length > 0 && !detectedSchemas.some((s) => s.type === "BreadcrumbList")) {
         recommendations.push("Add BreadcrumbList schema to improve navigation rich results.");
     }
+    const schemaIssues = deprecatedTypes.length + relativeUrls.length + invalidDates.length +
+        (missingContext ? 1 : 0) + duplicateEntities.length;
+    const score = detectedSchemas.length === 0
+        ? 0
+        : Math.max(0, Math.round(100 - (schemaIssues / detectedSchemas.length) * 25));
     return {
         url,
+        score,
         detectedSchemas,
         deprecatedTypes,
         missingContext,

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

@@ -1 +1 @@
-{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/analyzers/sitemap.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA8C9C,wCAAwC;AACxC,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,qBAAqB,CAAC,CA4DhC;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAuBvE"}
+{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/analyzers/sitemap.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA8C9C,wCAAwC;AACxC,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,qBAAqB,CAAC,CAsGhC;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAuBvE"}

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

@@ -52,39 +52,80 @@ export async function analyzeSitemap(sitemapUrl, config) {
     // Validate URLs.
     let invalidEntries = 0;
     const validUrls = [];
-    for (const u of parsed.urls) {
-        try {
-            new URL(u.loc);
-            validUrls.push(u.loc);
+    let childSitemapUrls = parsed.childSitemaps;
+    // Recursively resolve sitemap indexes up to 10 children.
+    if (parsed.isIndex && childSitemapUrls.length > 0) {
+        const childLimit = Math.min(childSitemapUrls.length, 10);
+        const childResults = await Promise.allSettled(childSitemapUrls.slice(0, childLimit).map((childUrl) => fetchPage(childUrl, config)));
+        for (let i = 0; i < childResults.length; i++) {
+            const child = childResults[i];
+            if (child.status === "fulfilled" && child.value.statusCode === 200) {
+                const childParsed = parseSitemapXml(child.value.content);
+                if (!childParsed.isIndex) {
+                    for (const u of childParsed.urls) {
+                        try {
+                            new URL(u.loc);
+                            validUrls.push(u.loc);
+                        }
+                        catch {
+                            invalidEntries++;
+                        }
+                    }
+                }
+                else {
+                    warnings.push(`Nested sitemap index at ${childSitemapUrls[i]} — only 2 levels supported.`);
+                }
+            }
+            else {
+                const err = child.status === "rejected" ? child.reason : child.value.statusCode;
+                warnings.push(`Failed to fetch child sitemap ${childSitemapUrls[i]}: ${err}`);
+            }
         }
-        catch {
-            invalidEntries++;
+        if (childSitemapUrls.length > 10) {
+            warnings.push(`Sitemap index has ${childSitemapUrls.length} children, only first 10 were fetched.`);
         }
     }
+    else {
+        for (const u of parsed.urls) {
+            try {
+                new URL(u.loc);
+                validUrls.push(u.loc);
+            }
+            catch {
+                invalidEntries++;
+            }
+        }
+    }
+    const totalUrls = validUrls.length;
     // Calculate lastmod coverage.
-    const withLastmod = parsed.urls.filter((u) => u.lastmod).length;
-    const lastmodCoverage = parsed.urls.length > 0
-        ? Math.round((withLastmod / parsed.urls.length) * 100)
-        : 0;
+    const withLastmod = parsed.isIndex ? 0 : parsed.urls.filter((u) => u.lastmod).length;
+    const lastmodCoverage = parsed.isIndex
+        ? 0
+        : parsed.urls.length > 0
+            ? Math.round((withLastmod / parsed.urls.length) * 100)
+            : 0;
+    if (parsed.isIndex) {
+        warnings.push(`Resolved ${validUrls.length} URLs from ${Math.min(childSitemapUrls.length, 10)} child sitemaps.`);
+    }
     // Size warnings.
-    if (result.contentLengthBytes > 50_000_000) {
+    if (!parsed.isIndex && result.contentLengthBytes > 50_000_000) {
         warnings.push("Sitemap exceeds 50MB uncompressed limit. Split into multiple sitemaps.");
     }
-    if (parsed.urls.length > 50_000) {
-        warnings.push("Sitemap contains more than 50,000 URLs. Split into multiple sitemaps.");
+    if (!parsed.isIndex && parsed.urls.length > 50_000) {
+        warnings.push(`Sitemap contains ${parsed.urls.length} URLs, exceeding the 50,000 limit. Split into multiple sitemaps.`);
     }
-    if (lastmodCoverage < 50 && parsed.urls.length > 0) {
+    if (!parsed.isIndex && lastmodCoverage < 50 && parsed.urls.length > 0) {
         warnings.push(`Only ${lastmodCoverage}% of URLs have lastmod dates. Adding lastmod improves crawl efficiency.`);
     }
     return {
         url: result.finalUrl,
-        urlCount: parsed.urls.length,
+        urlCount: totalUrls,
         urls: validUrls,
         lastmodCoverage,
         invalidEntries,
         sizeBytes: result.contentLengthBytes,
         isSitemapIndex: parsed.isIndex,
-        childSitemaps: parsed.childSitemaps,
+        childSitemaps: childSitemapUrls,
         warnings,
     };
 }

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

@@ -1,10 +1,3 @@
-/**
- * Technical SEO audit analyzer.
- *
- * Ported from the Python `seo-technical/SKILL.md` directives in claude-seo.
- * Audits crawlability, indexability, security, URL structure, mobile,
- * and AI crawler management — all using local HTTP fetches only.
- */
 import type { SeoConfig } from "../config.js";
 import type { FetchResult, PageData, TechnicalAuditResult } from "../types.js";
 export declare function auditTechnical(url: string, config: SeoConfig, pageData?: PageData, fetchResult?: FetchResult): Promise<TechnicalAuditResult>;

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

@@ -1 +1 @@
-{"version":3,"file":"technical.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/analyzers/technical.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAc,WAAW,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AA2D3F,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,EACjB,QAAQ,CAAC,EAAE,QAAQ,EACnB,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,oBAAoB,CAAC,CA+N/B"}
+{"version":3,"file":"technical.d.ts","sourceRoot":"","sources":["../../../../src/extensions/seo/analyzers/technical.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAc,WAAW,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAiE3F,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,EACjB,QAAQ,CAAC,EAAE,QAAQ,EACnB,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,oBAAoB,CAAC,CAqoB/B"}