recker 1.0.27 → 1.0.28-next.3bf98c7

package/dist/seo/rules/ecommerce.js

@@ -0,0 +1,252 @@
+import { createResult } from './types.js';
+export const ecommerceRules = [
+    {
+        id: 'ecommerce-product-schema',
+        name: 'Product Schema',
+        category: 'structured-data',
+        severity: 'warning',
+        description: 'Product pages should have Product schema for rich snippets',
+        check: (ctx) => {
+            if (!ctx.jsonLdTypes)
+                return null;
+            if (!ctx.isProductPage)
+                return null;
+            const hasProduct = ctx.jsonLdTypes.includes('Product');
+            if (!hasProduct) {
+                return createResult({ id: 'ecommerce-product-schema', name: 'Product Schema', category: 'structured-data', severity: 'warning' }, 'warn', 'Product page missing Product schema', {
+                    recommendation: 'Add Product structured data for rich snippets in search results',
+                    evidence: {
+                        expected: 'Product schema with name, image, price, availability',
+                        example: `{
+  "@type": "Product",
+  "name": "Product Name",
+  "image": "https://example.com/image.jpg",
+  "offers": {
+    "@type": "Offer",
+    "price": "99.99",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock"
+  }
+}`,
+                        learnMore: 'https://developers.google.com/search/docs/appearance/structured-data/product',
+                    },
+                });
+            }
+            return createResult({ id: 'ecommerce-product-schema', name: 'Product Schema', category: 'structured-data', severity: 'warning' }, 'pass', 'Product schema found');
+        },
+    },
+    {
+        id: 'ecommerce-product-price',
+        name: 'Product Price',
+        category: 'structured-data',
+        severity: 'warning',
+        description: 'Product schema should include price information',
+        check: (ctx) => {
+            if (!ctx.productSchema)
+                return null;
+            const hasPrice = ctx.productSchema.offers?.price !== undefined ||
+                ctx.productSchema.offers?.lowPrice !== undefined;
+            const hasCurrency = ctx.productSchema.offers?.priceCurrency !== undefined;
+            if (!hasPrice) {
+                return createResult({ id: 'ecommerce-product-price', name: 'Product Price', category: 'structured-data', severity: 'warning' }, 'warn', 'Product schema missing price', {
+                    recommendation: 'Add price to Product offers for price display in search results',
+                    evidence: {
+                        expected: 'offers.price or offers.lowPrice with priceCurrency',
+                        impact: 'Products without price may not show in Google Shopping results',
+                    },
+                });
+            }
+            if (!hasCurrency) {
+                return createResult({ id: 'ecommerce-product-price', name: 'Product Price', category: 'structured-data', severity: 'warning' }, 'warn', 'Product schema missing currency', {
+                    recommendation: 'Add priceCurrency (e.g., USD, EUR, BRL) to offers',
+                    evidence: {
+                        found: `price: ${ctx.productSchema.offers?.price}`,
+                        expected: 'priceCurrency: "USD" or similar ISO 4217 code',
+                    },
+                });
+            }
+            return createResult({ id: 'ecommerce-product-price', name: 'Product Price', category: 'structured-data', severity: 'warning' }, 'pass', `Price: ${ctx.productSchema.offers?.priceCurrency} ${ctx.productSchema.offers?.price || ctx.productSchema.offers?.lowPrice}`);
+        },
+    },
+    {
+        id: 'ecommerce-product-availability',
+        name: 'Product Availability',
+        category: 'structured-data',
+        severity: 'info',
+        description: 'Product schema should include availability status',
+        check: (ctx) => {
+            if (!ctx.productSchema?.offers)
+                return null;
+            const availability = ctx.productSchema.offers.availability;
+            if (!availability) {
+                return createResult({ id: 'ecommerce-product-availability', name: 'Product Availability', category: 'structured-data', severity: 'info' }, 'info', 'Product schema missing availability', {
+                    recommendation: 'Add availability to help users know if product is in stock',
+                    evidence: {
+                        expected: 'availability: "https://schema.org/InStock" or similar',
+                        example: 'InStock, OutOfStock, PreOrder, BackOrder, Discontinued',
+                        learnMore: 'https://schema.org/ItemAvailability',
+                    },
+                });
+            }
+            const availType = availability.replace('https://schema.org/', '').replace('http://schema.org/', '');
+            return createResult({ id: 'ecommerce-product-availability', name: 'Product Availability', category: 'structured-data', severity: 'info' }, 'pass', `Availability: ${availType}`);
+        },
+    },
+    {
+        id: 'ecommerce-product-image',
+        name: 'Product Image',
+        category: 'structured-data',
+        severity: 'warning',
+        description: 'Product schema should include high-quality images',
+        check: (ctx) => {
+            if (!ctx.productSchema)
+                return null;
+            const hasImage = ctx.productSchema.image !== undefined;
+            if (!hasImage) {
+                return createResult({ id: 'ecommerce-product-image', name: 'Product Image', category: 'structured-data', severity: 'warning' }, 'warn', 'Product schema missing image', {
+                    recommendation: 'Add product images for visual search results',
+                    evidence: {
+                        expected: 'At least one high-quality product image',
+                        impact: 'Products without images are less likely to appear in image search and shopping results',
+                    },
+                });
+            }
+            const imageCount = Array.isArray(ctx.productSchema.image)
+                ? ctx.productSchema.image.length
+                : 1;
+            return createResult({ id: 'ecommerce-product-image', name: 'Product Image', category: 'structured-data', severity: 'warning' }, 'pass', `${imageCount} product image(s) in schema`);
+        },
+    },
+    {
+        id: 'ecommerce-product-reviews',
+        name: 'Product Reviews',
+        category: 'structured-data',
+        severity: 'info',
+        description: 'Product schema can include aggregate ratings for star snippets',
+        check: (ctx) => {
+            if (!ctx.productSchema)
+                return null;
+            const hasRating = ctx.productSchema.aggregateRating !== undefined;
+            const hasReviews = ctx.productSchema.review !== undefined;
+            if (!hasRating && !hasReviews) {
+                return createResult({ id: 'ecommerce-product-reviews', name: 'Product Reviews', category: 'structured-data', severity: 'info' }, 'info', 'Product schema has no reviews or ratings', {
+                    recommendation: 'Add aggregateRating for star ratings in search results',
+                    evidence: {
+                        example: `"aggregateRating": {
+  "@type": "AggregateRating",
+  "ratingValue": "4.5",
+  "reviewCount": "42"
+}`,
+                        impact: 'Star ratings in search results can improve click-through rate by 20-30%',
+                    },
+                });
+            }
+            if (hasRating && ctx.productSchema.aggregateRating) {
+                const rating = ctx.productSchema.aggregateRating;
+                return createResult({ id: 'ecommerce-product-reviews', name: 'Product Reviews', category: 'structured-data', severity: 'info' }, 'pass', `Rating: ${rating.ratingValue ?? '?'}/5 (${rating.reviewCount ?? rating.ratingCount ?? '?'} reviews)`);
+            }
+            return createResult({ id: 'ecommerce-product-reviews', name: 'Product Reviews', category: 'structured-data', severity: 'info' }, 'pass', 'Product has review data');
+        },
+    },
+    {
+        id: 'ecommerce-product-brand',
+        name: 'Product Brand',
+        category: 'structured-data',
+        severity: 'info',
+        description: 'Product schema should include brand information',
+        check: (ctx) => {
+            if (!ctx.productSchema)
+                return null;
+            const hasBrand = ctx.productSchema.brand !== undefined;
+            if (!hasBrand) {
+                return createResult({ id: 'ecommerce-product-brand', name: 'Product Brand', category: 'structured-data', severity: 'info' }, 'info', 'Product schema missing brand', {
+                    recommendation: 'Add brand for better product identification',
+                    evidence: {
+                        example: `"brand": { "@type": "Brand", "name": "Brand Name" }`,
+                        impact: 'Brand helps Google understand product context for shopping queries',
+                    },
+                });
+            }
+            const brandName = typeof ctx.productSchema.brand === 'string'
+                ? ctx.productSchema.brand
+                : ctx.productSchema.brand?.name;
+            return createResult({ id: 'ecommerce-product-brand', name: 'Product Brand', category: 'structured-data', severity: 'info' }, 'pass', `Brand: ${brandName || 'specified'}`);
+        },
+    },
+    {
+        id: 'ecommerce-product-sku',
+        name: 'Product Identifiers',
+        category: 'structured-data',
+        severity: 'info',
+        description: 'Product schema should include unique identifiers (SKU, GTIN, MPN)',
+        check: (ctx) => {
+            if (!ctx.productSchema)
+                return null;
+            const hasSku = ctx.productSchema.sku !== undefined;
+            const hasGtin = ctx.productSchema.gtin !== undefined ||
+                ctx.productSchema.gtin13 !== undefined ||
+                ctx.productSchema.gtin14 !== undefined ||
+                ctx.productSchema.gtin8 !== undefined;
+            const hasMpn = ctx.productSchema.mpn !== undefined;
+            const identifiers = [];
+            if (hasSku)
+                identifiers.push('SKU');
+            if (hasGtin)
+                identifiers.push('GTIN');
+            if (hasMpn)
+                identifiers.push('MPN');
+            if (identifiers.length === 0) {
+                return createResult({ id: 'ecommerce-product-sku', name: 'Product Identifiers', category: 'structured-data', severity: 'info' }, 'info', 'Product schema missing identifiers', {
+                    recommendation: 'Add SKU, GTIN, or MPN for better product matching',
+                    evidence: {
+                        expected: 'At least one of: sku, gtin, gtin13, gtin14, gtin8, mpn',
+                        impact: 'Product identifiers help Google match products across retailers',
+                        learnMore: 'https://support.google.com/merchants/answer/6324461',
+                    },
+                });
+            }
+            return createResult({ id: 'ecommerce-product-sku', name: 'Product Identifiers', category: 'structured-data', severity: 'info' }, 'pass', `Identifiers: ${identifiers.join(', ')}`);
+        },
+    },
+    {
+        id: 'ecommerce-offer-valid-dates',
+        name: 'Offer Valid Dates',
+        category: 'structured-data',
+        severity: 'info',
+        description: 'Time-sensitive offers should have valid date ranges',
+        check: (ctx) => {
+            if (!ctx.productSchema?.offers)
+                return null;
+            const offers = ctx.productSchema.offers;
+            const priceValidUntil = offers.priceValidUntil;
+            const validFrom = offers.validFrom;
+            const validThrough = offers.validThrough;
+            if (priceValidUntil) {
+                const endDate = new Date(priceValidUntil);
+                const now = new Date();
+                if (endDate < now) {
+                    return createResult({ id: 'ecommerce-offer-valid-dates', name: 'Offer Valid Dates', category: 'structured-data', severity: 'info' }, 'warn', 'Offer priceValidUntil date has passed', {
+                        evidence: {
+                            found: priceValidUntil,
+                            issue: 'Expired offer dates should be updated or removed',
+                            impact: 'Expired dates may cause Google to distrust your pricing data',
+                        },
+                    });
+                }
+            }
+            if (validThrough) {
+                const endDate = new Date(validThrough);
+                const now = new Date();
+                if (endDate < now) {
+                    return createResult({ id: 'ecommerce-offer-valid-dates', name: 'Offer Valid Dates', category: 'structured-data', severity: 'info' }, 'warn', 'Offer validThrough date has passed', {
+                        evidence: {
+                            found: validThrough,
+                            issue: 'Expired validity dates should be updated',
+                        },
+                    });
+                }
+            }
+            return null;
+        },
+    },
+];

package/dist/seo/rules/i18n.d.ts

@@ -0,0 +1,2 @@
+import { SeoRule } from './types.js';
+export declare const i18nRules: SeoRule[];

package/dist/seo/rules/i18n.js

@@ -0,0 +1,222 @@
+import { createResult } from './types.js';
+export const i18nRules = [
+    {
+        id: 'i18n-hreflang-exists',
+        name: 'Hreflang Tags',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Multi-language sites should have hreflang tags for proper language targeting',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0) {
+                if (ctx.hasLang && ctx.langValue && ctx.langValue !== 'en') {
+                    return createResult({ id: 'i18n-hreflang-exists', name: 'Hreflang Tags', category: 'technical', severity: 'warning' }, 'info', 'No hreflang tags found (recommended for multi-language sites)', {
+                        recommendation: 'Add hreflang tags to indicate language/region alternatives',
+                        evidence: {
+                            expected: '<link rel="alternate" hreflang="en" href="https://example.com/en/">',
+                            example: '<link rel="alternate" hreflang="en" href="https://example.com/en/">\n<link rel="alternate" hreflang="es" href="https://example.com/es/">\n<link rel="alternate" hreflang="x-default" href="https://example.com/">',
+                            impact: 'Without hreflang, search engines may show wrong language version to users in different countries',
+                            learnMore: 'https://developers.google.com/search/docs/specialty/international/localized-versions',
+                        },
+                    });
+                }
+                return null;
+            }
+            return createResult({ id: 'i18n-hreflang-exists', name: 'Hreflang Tags', category: 'technical', severity: 'warning' }, 'pass', `${ctx.hreflangTags.length} hreflang tag(s) found`, { value: ctx.hreflangTags.length });
+        },
+    },
+    {
+        id: 'i18n-hreflang-self',
+        name: 'Hreflang Self-Reference',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Hreflang tags should include a self-referencing tag for the current page',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0)
+                return null;
+            if (!ctx.url)
+                return null;
+            const currentUrl = ctx.url.toLowerCase().replace(/\/$/, '');
+            const hasSelfRef = ctx.hreflangTags.some((tag) => {
+                const href = tag.href?.toLowerCase().replace(/\/$/, '');
+                return href === currentUrl;
+            });
+            if (!hasSelfRef) {
+                return createResult({ id: 'i18n-hreflang-self', name: 'Hreflang Self-Reference', category: 'technical', severity: 'warning' }, 'warn', 'Missing self-referencing hreflang tag', {
+                    recommendation: 'Add a hreflang tag that points to the current page',
+                    evidence: {
+                        found: `Current URL: ${ctx.url}`,
+                        expected: `<link rel="alternate" hreflang="${ctx.langValue || 'en'}" href="${ctx.url}">`,
+                        impact: 'Google recommends including a self-referencing hreflang tag for clarity',
+                    },
+                });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'i18n-hreflang-x-default',
+        name: 'Hreflang X-Default',
+        category: 'technical',
+        severity: 'info',
+        description: 'Include x-default hreflang for users outside defined regions',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length < 2)
+                return null;
+            const hasXDefault = ctx.hreflangTags.some((tag) => tag.lang === 'x-default');
+            if (!hasXDefault) {
+                return createResult({ id: 'i18n-hreflang-x-default', name: 'Hreflang X-Default', category: 'technical', severity: 'info' }, 'info', 'No x-default hreflang tag found', {
+                    recommendation: 'Add hreflang="x-default" to specify the fallback page for unmatched languages',
+                    evidence: {
+                        expected: '<link rel="alternate" hreflang="x-default" href="https://example.com/">',
+                        impact: 'Without x-default, users in unsupported regions may not see the best version',
+                    },
+                });
+            }
+            return createResult({ id: 'i18n-hreflang-x-default', name: 'Hreflang X-Default', category: 'technical', severity: 'info' }, 'pass', 'x-default hreflang tag present');
+        },
+    },
+    {
+        id: 'i18n-hreflang-valid-codes',
+        name: 'Hreflang Valid Codes',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Hreflang language codes must be valid ISO 639-1 codes',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0)
+                return null;
+            const validLanguageCodes = new Set([
+                'aa', 'ab', 'af', 'ak', 'sq', 'am', 'ar', 'an', 'hy', 'as', 'av', 'ae', 'ay', 'az',
+                'ba', 'bm', 'eu', 'be', 'bn', 'bh', 'bi', 'bo', 'bs', 'br', 'bg', 'my', 'ca', 'cs',
+                'ch', 'ce', 'zh', 'cu', 'cv', 'kw', 'co', 'cr', 'cy', 'da', 'de', 'dv', 'nl', 'dz',
+                'en', 'eo', 'et', 'ee', 'fo', 'fa', 'fj', 'fi', 'fr', 'fy', 'ff', 'ka', 'el', 'gn',
+                'gu', 'ht', 'ha', 'he', 'hz', 'hi', 'ho', 'hr', 'hu', 'ig', 'is', 'io', 'ii', 'iu',
+                'ie', 'ia', 'id', 'ik', 'it', 'jv', 'ja', 'kl', 'kn', 'ks', 'kr', 'kk', 'km', 'ki',
+                'rw', 'ky', 'kv', 'kg', 'ko', 'kj', 'ku', 'lo', 'la', 'lv', 'li', 'ln', 'lt', 'lb',
+                'lu', 'lg', 'mk', 'mh', 'ml', 'mi', 'mr', 'ms', 'mg', 'mt', 'mn', 'na', 'nv', 'nr',
+                'nd', 'ng', 'ne', 'nn', 'nb', 'no', 'ny', 'oc', 'oj', 'or', 'om', 'os', 'pa', 'pi',
+                'pl', 'pt', 'ps', 'qu', 'rm', 'ro', 'rn', 'ru', 'sg', 'sa', 'si', 'sk', 'sl', 'se',
+                'sm', 'sn', 'sd', 'so', 'st', 'es', 'sc', 'sr', 'ss', 'su', 'sw', 'sv', 'ty', 'ta',
+                'tt', 'te', 'tg', 'tl', 'th', 'ti', 'to', 'tn', 'ts', 'tk', 'tr', 'tw', 'ug', 'uk',
+                'ur', 'uz', 've', 'vi', 'vo', 'wa', 'wo', 'xh', 'yi', 'yo', 'za', 'zu',
+                'x-default',
+            ]);
+            const invalidTags = [];
+            for (const tag of ctx.hreflangTags) {
+                const lang = tag.lang?.toLowerCase().split('-')[0];
+                if (lang && !validLanguageCodes.has(lang)) {
+                    invalidTags.push(tag.lang);
+                }
+            }
+            if (invalidTags.length > 0) {
+                return createResult({ id: 'i18n-hreflang-valid-codes', name: 'Hreflang Valid Codes', category: 'technical', severity: 'warning' }, 'warn', `Invalid hreflang codes: ${invalidTags.join(', ')}`, {
+                    recommendation: 'Use valid ISO 639-1 language codes',
+                    evidence: {
+                        found: invalidTags,
+                        expected: 'Valid ISO 639-1 codes like: en, es, fr, de, pt-BR, zh-CN',
+                        learnMore: 'https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes',
+                    },
+                });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'i18n-hreflang-return-links',
+        name: 'Hreflang Return Links',
+        category: 'technical',
+        severity: 'warning',
+        description: 'All hreflang URLs should return links back to this page (bidirectional)',
+        check: (ctx) => {
+            if (!ctx.hreflangTags || ctx.hreflangTags.length < 2)
+                return null;
+            return createResult({ id: 'i18n-hreflang-return-links', name: 'Hreflang Return Links', category: 'technical', severity: 'warning' }, 'info', 'Hreflang return links cannot be verified from HTML alone', {
+                recommendation: 'Ensure all alternate pages link back to this page with matching hreflang tags',
+                evidence: {
+                    impact: 'Missing return links can cause Google to ignore hreflang annotations',
+                    learnMore: 'https://developers.google.com/search/docs/specialty/international/localized-versions#bidirectional',
+                },
+            });
+        },
+    },
+    {
+        id: 'i18n-content-language',
+        name: 'Content-Language Header',
+        category: 'technical',
+        severity: 'info',
+        description: 'Content-Language header can indicate the language of the document',
+        check: (ctx) => {
+            if (!ctx.responseHeaders)
+                return null;
+            const contentLang = ctx.responseHeaders['content-language'] || ctx.responseHeaders['Content-Language'];
+            if (!contentLang) {
+                if (ctx.hasLang) {
+                    return createResult({ id: 'i18n-content-language', name: 'Content-Language Header', category: 'technical', severity: 'info' }, 'info', 'Content-Language header not set', {
+                        recommendation: `Consider adding Content-Language: ${ctx.langValue || 'en'} header`,
+                        evidence: {
+                            impact: 'While not critical for SEO, it helps with content negotiation',
+                        },
+                    });
+                }
+                return null;
+            }
+            if (ctx.langValue) {
+                const headerLang = Array.isArray(contentLang) ? contentLang[0] : contentLang;
+                const headerLangPrimary = headerLang.toLowerCase().split('-')[0].split(',')[0].trim();
+                const htmlLangPrimary = ctx.langValue.toLowerCase().split('-')[0];
+                if (headerLangPrimary !== htmlLangPrimary) {
+                    return createResult({ id: 'i18n-content-language', name: 'Content-Language Header', category: 'technical', severity: 'info' }, 'warn', `Content-Language (${headerLang}) doesn't match html lang (${ctx.langValue})`, {
+                        recommendation: 'Ensure Content-Language header matches the html lang attribute',
+                    });
+                }
+            }
+            return createResult({ id: 'i18n-content-language', name: 'Content-Language Header', category: 'technical', severity: 'info' }, 'pass', `Content-Language: ${contentLang}`);
+        },
+    },
+    {
+        id: 'i18n-lang-consistency',
+        name: 'Language Consistency',
+        category: 'technical',
+        severity: 'warning',
+        description: 'HTML lang attribute should match the og:locale if present',
+        check: (ctx) => {
+            if (!ctx.hasLang || !ctx.ogLocale)
+                return null;
+            const htmlLang = ctx.langValue?.toLowerCase().split('-')[0];
+            const ogLocaleLang = ctx.ogLocale.toLowerCase().split('_')[0];
+            if (htmlLang !== ogLocaleLang) {
+                return createResult({ id: 'i18n-lang-consistency', name: 'Language Consistency', category: 'technical', severity: 'warning' }, 'warn', `Language mismatch: html lang="${ctx.langValue}" vs og:locale="${ctx.ogLocale}"`, {
+                    recommendation: 'Ensure html lang and og:locale represent the same language',
+                    evidence: {
+                        found: [`html lang="${ctx.langValue}"`, `og:locale="${ctx.ogLocale}"`],
+                        impact: 'Inconsistent language signals can confuse search engines and social platforms',
+                    },
+                });
+            }
+            return null;
+        },
+    },
+    {
+        id: 'i18n-lang-region',
+        name: 'Language Region Specificity',
+        category: 'technical',
+        severity: 'info',
+        description: 'Consider using region-specific language codes for better targeting',
+        check: (ctx) => {
+            if (!ctx.hasLang || !ctx.langValue)
+                return null;
+            const multiRegionalLangs = ['en', 'es', 'pt', 'zh', 'fr', 'de', 'ar'];
+            const langPrimary = ctx.langValue.toLowerCase().split('-')[0];
+            if (multiRegionalLangs.includes(langPrimary) && !ctx.langValue.includes('-')) {
+                return createResult({ id: 'i18n-lang-region', name: 'Language Region Specificity', category: 'technical', severity: 'info' }, 'info', `Consider using region-specific lang code (e.g., ${langPrimary}-US, ${langPrimary}-GB)`, {
+                    recommendation: 'For multi-regional languages, specify the region for better targeting',
+                    evidence: {
+                        found: ctx.langValue,
+                        expected: `${langPrimary}-XX (e.g., en-US, es-ES, pt-BR, zh-CN)`,
+                        impact: 'Helps search engines serve the right regional variant',
+                    },
+                });
+            }
+            return null;
+        },
+    },
+];

package/dist/seo/rules/images.d.ts

@@ -0,0 +1,2 @@
+import { SeoRule } from './types.js';
+export declare const imageRules: SeoRule[];