recker 1.0.43 → 1.0.44

package/dist/seo/rules/i18n.js

@@ -19,7 +19,9 @@ export const i18nRules = [
                         },
                     });
                 }
-                return null;
+                return createResult({ id: 'i18n-hreflang-exists', name: 'Hreflang Tags', category: 'technical', severity: 'warning' }, 'info', 'No hreflang tags found', {
+                    recommendation: 'Consider adding hreflang tags if you have multi-language versions of this page',
+                });
             }
             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 });
         },
@@ -31,10 +33,14 @@ export const i18nRules = [
         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;
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0) {
+                return createResult({ id: 'i18n-hreflang-self', name: 'Hreflang Self-Reference', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no hreflang tags)', {
+                    recommendation: 'Add hreflang tags first, then ensure self-reference is included',
+                });
+            }
+            if (!ctx.url) {
+                return createResult({ id: 'i18n-hreflang-self', name: 'Hreflang Self-Reference', category: 'technical', severity: 'warning' }, 'info', 'Cannot verify (URL not available)');
+            }
             const currentUrl = ctx.url.toLowerCase().replace(/\/$/, '');
             const hasSelfRef = ctx.hreflangTags.some((tag) => {
                 const href = tag.href?.toLowerCase().replace(/\/$/, '');
@@ -47,10 +53,11 @@ export const i18nRules = [
                         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',
+                        example: `<link rel="alternate" hreflang="en" href="${ctx.url}">\n<link rel="alternate" hreflang="es" href="${ctx.url.replace(/\/en\//, '/es/')}">`,
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'i18n-hreflang-self', name: 'Hreflang Self-Reference', category: 'technical', severity: 'warning' }, 'pass', 'Self-referencing hreflang tag present');
         },
     },
     {
@@ -60,8 +67,11 @@ export const i18nRules = [
         severity: 'info',
         description: 'Include x-default hreflang for users outside defined regions',
         check: (ctx) => {
-            if (!ctx.hreflangTags || ctx.hreflangTags.length < 2)
-                return null;
+            if (!ctx.hreflangTags || ctx.hreflangTags.length < 2) {
+                return createResult({ id: 'i18n-hreflang-x-default', name: 'Hreflang X-Default', category: 'technical', severity: 'info' }, 'info', 'Not applicable (need 2+ hreflang tags for x-default)', {
+                    recommendation: 'Add multiple hreflang tags to support international visitors',
+                });
+            }
             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', {
@@ -82,8 +92,9 @@ export const i18nRules = [
         severity: 'warning',
         description: 'Hreflang language codes must be valid ISO 639-1 codes',
         check: (ctx) => {
-            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0)
-                return null;
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0) {
+                return createResult({ id: 'i18n-hreflang-valid-codes', name: 'Hreflang Valid Codes', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no hreflang tags)');
+            }
             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',
@@ -113,11 +124,13 @@ export const i18nRules = [
                     evidence: {
                         found: invalidTags,
                         expected: 'Valid ISO 639-1 codes like: en, es, fr, de, pt-BR, zh-CN',
+                        impact: 'Invalid language codes will be ignored by search engines, breaking international targeting',
+                        example: '<link rel="alternate" hreflang="en-US" href="https://example.com/en/">\n<link rel="alternate" hreflang="es-ES" href="https://example.com/es/">',
                         learnMore: 'https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes',
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'i18n-hreflang-valid-codes', name: 'Hreflang Valid Codes', category: 'technical', severity: 'warning' }, 'pass', 'All hreflang codes are valid ISO 639-1');
         },
     },
     {
@@ -127,8 +140,11 @@ export const i18nRules = [
         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;
+            if (!ctx.hreflangTags || ctx.hreflangTags.length < 2) {
+                return createResult({ id: 'i18n-hreflang-return-links', name: 'Hreflang Return Links', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (need 2+ hreflang tags)', {
+                    recommendation: 'Add hreflang tags to enable return link verification',
+                });
+            }
             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: {
@@ -145,19 +161,17 @@ export const i18nRules = [
         severity: 'info',
         description: 'Content-Language header can indicate the language of the document',
         check: (ctx) => {
-            if (!ctx.responseHeaders)
-                return null;
+            if (!ctx.responseHeaders) {
+                return createResult({ id: 'i18n-content-language', name: 'Content-Language Header', category: 'technical', severity: 'info' }, 'info', 'Cannot verify (response headers not available)');
+            }
             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;
+                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',
+                    },
+                });
             }
             if (ctx.langValue) {
                 const headerLang = Array.isArray(contentLang) ? contentLang[0] : contentLang;
@@ -166,6 +180,11 @@ export const i18nRules = [
                 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',
+                        evidence: {
+                            found: `Content-Language: ${headerLang}, html lang="${ctx.langValue}"`,
+                            expected: 'Both should declare the same language',
+                            impact: 'Mismatched language declarations can confuse browsers and search engines',
+                        },
                     });
                 }
             }
@@ -179,8 +198,18 @@ export const i18nRules = [
         severity: 'warning',
         description: 'HTML lang attribute should match the og:locale if present',
         check: (ctx) => {
-            if (!ctx.hasLang || !ctx.ogLocale)
-                return null;
+            if (!ctx.hasLang && !ctx.ogLocale) {
+                return createResult({ id: 'i18n-lang-consistency', name: 'Language Consistency', category: 'technical', severity: 'warning' }, 'info', 'No lang attribute or og:locale to compare', {
+                    recommendation: 'Add html lang attribute and og:locale for language consistency',
+                });
+            }
+            if (!ctx.hasLang || !ctx.ogLocale) {
+                return createResult({ id: 'i18n-lang-consistency', name: 'Language Consistency', category: 'technical', severity: 'warning' }, 'info', ctx.hasLang ? 'No og:locale to compare with html lang' : 'No html lang to compare with og:locale', {
+                    recommendation: ctx.hasLang
+                        ? 'Add og:locale meta tag for social platforms'
+                        : 'Add html lang attribute for language declaration',
+                });
+            }
             const htmlLang = ctx.langValue?.toLowerCase().split('-')[0];
             const ogLocaleLang = ctx.ogLocale.toLowerCase().split('_')[0];
             if (htmlLang !== ogLocaleLang) {
@@ -188,11 +217,13 @@ export const i18nRules = [
                     recommendation: 'Ensure html lang and og:locale represent the same language',
                     evidence: {
                         found: [`html lang="${ctx.langValue}"`, `og:locale="${ctx.ogLocale}"`],
+                        expected: 'Both attributes should use the same language code',
                         impact: 'Inconsistent language signals can confuse search engines and social platforms',
+                        example: '<html lang="en">\n<meta property="og:locale" content="en_US">',
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'i18n-lang-consistency', name: 'Language Consistency', category: 'technical', severity: 'warning' }, 'pass', `Language consistent: html lang="${ctx.langValue}", og:locale="${ctx.ogLocale}"`);
         },
     },
     {
@@ -202,8 +233,11 @@ export const i18nRules = [
         severity: 'info',
         description: 'Consider using region-specific language codes for better targeting',
         check: (ctx) => {
-            if (!ctx.hasLang || !ctx.langValue)
-                return null;
+            if (!ctx.hasLang || !ctx.langValue) {
+                return createResult({ id: 'i18n-lang-region', name: 'Language Region Specificity', category: 'technical', severity: 'info' }, 'info', 'No lang attribute to analyze', {
+                    recommendation: 'Add html lang attribute first',
+                });
+            }
             const multiRegionalLangs = ['en', 'es', 'pt', 'zh', 'fr', 'de', 'ar'];
             const langPrimary = ctx.langValue.toLowerCase().split('-')[0];
             if (multiRegionalLangs.includes(langPrimary) && !ctx.langValue.includes('-')) {
@@ -216,7 +250,7 @@ export const i18nRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'i18n-lang-region', name: 'Language Region Specificity', category: 'technical', severity: 'info' }, 'pass', `Lang attribute: ${ctx.langValue}`);
         },
     },
     {
@@ -226,8 +260,12 @@ export const i18nRules = [
         severity: 'warning',
         description: 'Hreflang language should match page content language',
         check: (ctx) => {
-            if (!ctx.hreflangTags || !ctx.detectedLanguage)
-                return null;
+            if (!ctx.hreflangTags || ctx.hreflangTags.length === 0) {
+                return createResult({ id: 'hreflang-language-mismatch', name: 'Hreflang Language Mismatch', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no hreflang tags)');
+            }
+            if (!ctx.detectedLanguage) {
+                return createResult({ id: 'hreflang-language-mismatch', name: 'Hreflang Language Mismatch', category: 'technical', severity: 'warning' }, 'info', 'Cannot verify (language detection not available)');
+            }
             const selfHreflang = ctx.hreflangTags.find(tag => tag.href === ctx.url || tag.href === ctx.canonicalUrl);
             if (selfHreflang && ctx.detectedLanguage) {
                 const hreflangLang = selfHreflang.lang.split('-')[0].toLowerCase();
@@ -236,14 +274,15 @@ export const i18nRules = [
                     return createResult({ id: 'hreflang-language-mismatch', name: 'Hreflang Language Mismatch', category: 'technical', severity: 'warning' }, 'warn', `Hreflang declares "${selfHreflang.lang}" but content appears to be "${ctx.detectedLanguage}"`, {
                         recommendation: 'Verify the hreflang attribute matches the actual page language',
                         evidence: {
-                            found: `hreflang="${selfHreflang.lang}"`,
-                            expected: `Content language: ${ctx.detectedLanguage}`,
-                            impact: 'Language mismatch may confuse search engines and affect international SEO'
+                            found: `hreflang="${selfHreflang.lang}", detected content language: "${ctx.detectedLanguage}"`,
+                            expected: `hreflang="${ctx.detectedLanguage}"`,
+                            impact: 'Language mismatch may confuse search engines and affect international SEO',
+                            example: `<link rel="alternate" hreflang="${ctx.detectedLanguage}" href="${ctx.url}">`,
                         }
                     });
                 }
             }
-            return null;
+            return createResult({ id: 'hreflang-language-mismatch', name: 'Hreflang Language Mismatch', category: 'technical', severity: 'warning' }, 'pass', 'Hreflang language matches detected content language');
         },
     },
 ];

package/dist/seo/rules/images.js

@@ -8,13 +8,24 @@ export const imageRules = [
         severity: 'error',
         description: 'All images must have alt text',
         check: (ctx) => {
-            if (ctx.totalImages === undefined || ctx.totalImages === 0)
-                return null;
+            if (ctx.totalImages === undefined || ctx.totalImages === 0) {
+                return createResult({ id: 'images-alt-text', name: 'Image Alt Text', category: 'images', severity: 'error' }, 'info', 'Not applicable (no images detected)', { recommendation: 'This rule ensures all images have descriptive alt text for accessibility and SEO' });
+            }
             const withoutAlt = ctx.imagesWithoutAlt ?? 0;
             if (withoutAlt > 0) {
                 const percentage = Math.round((withoutAlt / ctx.totalImages) * 100);
                 const severity = withoutAlt > ctx.totalImages / 2 ? 'fail' : 'warn';
-                return createResult({ id: 'images-alt-text', name: 'Image Alt Text', category: 'images', severity: 'error' }, severity, `${withoutAlt} of ${ctx.totalImages} images missing alt text (${percentage}%)`, { value: withoutAlt, recommendation: 'Add descriptive alt text to all images' });
+                return createResult({ id: 'images-alt-text', name: 'Image Alt Text', category: 'images', severity: 'error' }, severity, `${withoutAlt} of ${ctx.totalImages} images missing alt text (${percentage}%)`, {
+                    value: withoutAlt,
+                    recommendation: 'Add descriptive alt text to all images. Describe what the image shows and its relevance to the content.',
+                    evidence: {
+                        found: `${withoutAlt} images without alt attribute`,
+                        expected: 'All images should have meaningful alt text',
+                        impact: 'Missing alt text hurts accessibility (screen readers) and prevents images from appearing in Google Image Search. Alt text is also used as anchor text when images are linked.',
+                        example: '<img src="product.jpg" alt="Red leather wallet with zipper closure - front view">',
+                        learnMore: 'https://developers.google.com/search/docs/appearance/google-images#use-descriptive-alt-text'
+                    }
+                });
             }
             return createResult({ id: 'images-alt-text', name: 'Image Alt Text', category: 'images', severity: 'error' }, 'pass', 'All images have alt text');
         },
@@ -26,11 +37,23 @@ export const imageRules = [
         severity: 'warning',
         description: 'Images should have width and height attributes to prevent CLS',
         check: (ctx) => {
-            if (ctx.totalImages === undefined || ctx.totalImages === 0)
-                return null;
+            if (ctx.totalImages === undefined || ctx.totalImages === 0) {
+                return createResult({ id: 'images-dimensions', name: 'Image Dimensions', category: 'images', severity: 'warning' }, 'info', 'Not applicable (no images detected)', { recommendation: 'This rule checks that images have width and height attributes to prevent layout shifts' });
+            }
             const missing = ctx.imagesMissingDimensions ?? 0;
             if (missing > 0) {
-                return createResult({ id: 'images-dimensions', name: 'Image Dimensions', category: 'images', severity: 'warning' }, 'warn', `${missing} images missing width/height attributes`, { value: missing, recommendation: 'Add width and height to prevent layout shifts (CLS)' });
+                const percentage = Math.round((missing / ctx.totalImages) * 100);
+                return createResult({ id: 'images-dimensions', name: 'Image Dimensions', category: 'images', severity: 'warning' }, 'warn', `${missing} of ${ctx.totalImages} images missing width/height (${percentage}%)`, {
+                    value: missing,
+                    recommendation: 'Add explicit width and height attributes to all images to reserve space and prevent layout shifts.',
+                    evidence: {
+                        found: `${missing} images without dimensions`,
+                        expected: 'All images should have width and height attributes',
+                        impact: 'Images without dimensions cause Cumulative Layout Shift (CLS), which negatively affects Core Web Vitals and user experience.',
+                        example: '<img src="photo.jpg" width="800" height="600" alt="Description">',
+                        learnMore: 'https://web.dev/optimize-cls/#images-without-dimensions'
+                    }
+                });
             }
             return createResult({ id: 'images-dimensions', name: 'Image Dimensions', category: 'images', severity: 'warning' }, 'pass', 'All images have dimensions defined');
         },
@@ -42,11 +65,21 @@ export const imageRules = [
         severity: 'info',
         description: 'Below-the-fold images should use lazy loading',
         check: (ctx) => {
-            if (ctx.totalImages === undefined || ctx.totalImages <= 3)
-                return null;
+            if (ctx.totalImages === undefined || ctx.totalImages <= 3) {
+                return createResult({ id: 'images-lazy-loading', name: 'Lazy Loading', category: 'images', severity: 'info' }, 'info', 'Not applicable (too few images to require lazy loading)', { recommendation: 'This rule checks for lazy loading on pages with multiple images' });
+            }
             const lazy = ctx.imagesWithLazyLoad ?? 0;
             if (lazy === 0) {
-                return createResult({ id: 'images-lazy-loading', name: 'Lazy Loading', category: 'images', severity: 'info' }, 'info', 'No images use lazy loading', { recommendation: 'Add loading="lazy" to below-the-fold images' });
+                return createResult({ id: 'images-lazy-loading', name: 'Lazy Loading', category: 'images', severity: 'info' }, 'info', 'No images use lazy loading', {
+                    recommendation: 'Add loading="lazy" to below-the-fold images to defer loading until they are near the viewport.',
+                    evidence: {
+                        found: 'No images with loading="lazy"',
+                        expected: 'Below-the-fold images should use lazy loading',
+                        impact: 'Lazy loading reduces initial page load time, saves bandwidth, and improves Core Web Vitals (LCP).',
+                        example: '<img src="photo.jpg" loading="lazy" alt="Description">',
+                        learnMore: 'https://web.dev/browser-level-image-lazy-loading/'
+                    }
+                });
             }
             return createResult({ id: 'images-lazy-loading', name: 'Lazy Loading', category: 'images', severity: 'info' }, 'pass', `${lazy} images use lazy loading`);
         },
@@ -58,11 +91,22 @@ export const imageRules = [
         severity: 'info',
         description: 'Images should use modern formats like WebP or AVIF',
         check: (ctx) => {
-            if (ctx.totalImages === undefined || ctx.totalImages === 0)
-                return null;
+            if (ctx.totalImages === undefined || ctx.totalImages === 0) {
+                return createResult({ id: 'images-format-modern', name: 'Modern Image Formats', category: 'images', severity: 'info' }, 'info', 'Not applicable (no images detected)', { recommendation: 'This rule checks for modern image formats like WebP and AVIF for better performance' });
+            }
             const modern = ctx.imagesUsingModernFormats ?? 0;
             if (ctx.totalImages > 0 && modern === 0) {
-                return createResult({ id: 'images-format-modern', name: 'Modern Image Formats', category: 'images', severity: 'info' }, 'info', 'No images using modern formats (WebP/AVIF)', { value: modern, recommendation: 'Serve images in WebP or AVIF format for better compression' });
+                return createResult({ id: 'images-format-modern', name: 'Modern Image Formats', category: 'images', severity: 'info' }, 'info', 'No images using modern formats (WebP/AVIF)', {
+                    value: modern,
+                    recommendation: 'Convert images to WebP or AVIF format for 25-50% smaller file sizes with same quality.',
+                    evidence: {
+                        found: 'Only traditional formats (JPEG, PNG, GIF)',
+                        expected: 'At least some images in WebP or AVIF format',
+                        impact: 'Modern formats significantly reduce page weight and improve load times. WebP has 94% browser support.',
+                        example: '<picture>\n  <source srcset="image.avif" type="image/avif">\n  <source srcset="image.webp" type="image/webp">\n  <img src="image.jpg" alt="Description">\n</picture>',
+                        learnMore: 'https://web.dev/uses-webp-images/'
+                    }
+                });
             }
             return createResult({ id: 'images-format-modern', name: 'Modern Image Formats', category: 'images', severity: 'info' }, 'pass', `${modern} images using modern formats`, { value: modern });
         },
@@ -78,7 +122,7 @@ export const imageRules = [
             if (emptyAlt > 0) {
                 return createResult({ id: 'images-empty-alt', name: 'Empty Alt Text', category: 'images', severity: 'info' }, 'info', `${emptyAlt} image(s) with empty alt="" (decorative)`, { value: emptyAlt, recommendation: 'Ensure these images are truly decorative' });
             }
-            return null;
+            return createResult({ id: 'images-empty-alt', name: 'Empty Alt Text', category: 'images', severity: 'info' }, 'pass', 'No images with empty alt attributes');
         },
     },
     {
@@ -88,8 +132,9 @@ export const imageRules = [
         severity: 'warning',
         description: 'Alt text should be descriptive (ideal 80-120, max 150 chars)',
         check: (ctx) => {
-            if (!ctx.altTextLengths || ctx.altTextLengths.length === 0)
-                return null;
+            if (!ctx.altTextLengths || ctx.altTextLengths.length === 0) {
+                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'info', 'Not applicable (no alt text data available)', { recommendation: 'This rule checks alt text length to ensure descriptions are meaningful' });
+            }
             const { minLength, idealLength, maxLength } = SEO_THRESHOLDS.images.alt;
             let shortAlts = 0;
             let longAlts = 0;
@@ -103,15 +148,35 @@ export const imageRules = [
                     nonIdealAlts++;
             });
             if (shortAlts > 0) {
-                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'warn', `${shortAlts} alt text(s) are too short (min: ${minLength} chars)`, { value: shortAlts, recommendation: `Make alt texts more descriptive, at least ${minLength} characters.` });
+                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'warn', `${shortAlts} alt text(s) are too short (min: ${minLength} chars)`, {
+                    value: shortAlts,
+                    recommendation: `Make alt texts more descriptive, at least ${minLength} characters.`,
+                    evidence: {
+                        found: `${shortAlts} alt text(s) with less than ${minLength} characters`,
+                        expected: `Alt text should be at least ${minLength} characters to be meaningful`,
+                        impact: 'Very short alt text (like "logo" or "pic") doesn\'t provide enough context for screen readers or search engines, reducing accessibility and SEO value.',
+                        example: 'Instead of alt="logo", use alt="Acme Corp logo - handshake symbol representing trust"',
+                        learnMore: 'https://www.w3.org/WAI/tutorials/images/'
+                    }
+                });
             }
             if (longAlts > 0) {
-                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'warn', `${longAlts} alt text(s) are too long (max: ${maxLength} chars)`, { value: longAlts, recommendation: `Shorten alt texts to be concise, under ${maxLength} characters.` });
+                return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'warn', `${longAlts} alt text(s) are too long (max: ${maxLength} chars)`, {
+                    value: longAlts,
+                    recommendation: `Shorten alt texts to be concise, under ${maxLength} characters.`,
+                    evidence: {
+                        found: `${longAlts} alt text(s) exceeding ${maxLength} characters`,
+                        expected: `Alt text should be under ${maxLength} characters for optimal accessibility`,
+                        impact: 'Excessively long alt text can be tedious for screen reader users and may get truncated in search results. Keep it concise while still being descriptive.',
+                        example: 'Instead of a long paragraph, use concise descriptions like: alt="Professional headshot of Jane Smith, CEO, wearing navy blue suit"',
+                        learnMore: 'https://www.w3.org/WAI/tutorials/images/'
+                    }
+                });
             }
             if (nonIdealAlts > 0) {
                 return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'info' }, 'info', `${nonIdealAlts} alt text(s) are not in the ideal length range (${idealLength.min}-${idealLength.max} chars)`, { value: nonIdealAlts, recommendation: `Aim for alt texts between ${idealLength.min} and ${idealLength.max} characters for best results.` });
             }
-            return null;
+            return createResult({ id: 'images-alt-length', name: 'Alt Text Length', category: 'images', severity: 'warning' }, 'pass', 'All alt text lengths are within ideal range');
         },
     },
     {
@@ -121,15 +186,26 @@ export const imageRules = [
         severity: 'info',
         description: 'Image filenames should be descriptive and use keywords, not generic names.',
         check: (ctx) => {
-            if (!ctx.imageFilenames || ctx.imageFilenames.length === 0)
-                return null;
+            if (!ctx.imageFilenames || ctx.imageFilenames.length === 0) {
+                return createResult({ id: 'images-clean-filenames', name: 'Image Filenames', category: 'images', severity: 'info' }, 'info', 'Not applicable (no image filename data available)', { recommendation: 'This rule checks for descriptive image filenames with keywords' });
+            }
             const genericFilenames = ctx.imageFilenames.filter(name => /^(img|image|photo|pic)\d*\.(jpg|jpeg|png|webp|avif|gif)$/i.test(name) ||
                 /^screenshot_\d*\.(jpg|jpeg|png)$/i.test(name) ||
                 /^untitled-\d*\.(jpg|jpeg|png)$/i.test(name));
             if (genericFilenames.length > 0) {
-                return createResult({ id: 'images-clean-filenames', name: 'Image Filenames', category: 'images', severity: 'warning' }, 'warn', `${genericFilenames.length} image(s) have generic filenames (e.g., IMG_1234.jpg)`, { value: genericFilenames.length, recommendation: 'Rename image files to be descriptive and include keywords (e.g., open-graph-example.jpg).' });
+                return createResult({ id: 'images-clean-filenames', name: 'Image Filenames', category: 'images', severity: 'warning' }, 'warn', `${genericFilenames.length} image(s) have generic filenames`, {
+                    value: genericFilenames.length,
+                    recommendation: 'Rename image files to be descriptive and include relevant keywords.',
+                    evidence: {
+                        found: genericFilenames.slice(0, 5),
+                        expected: 'Descriptive filenames with keywords (e.g., red-leather-wallet-front.jpg)',
+                        impact: 'Image filenames are used by search engines to understand image content and can appear in Google Image Search.',
+                        example: 'Instead of "IMG_1234.jpg", use "blue-running-shoes-nike-air.jpg"',
+                        learnMore: 'https://developers.google.com/search/docs/appearance/google-images#descriptive-titles-captions-filenames'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'images-clean-filenames', name: 'Image Filenames', category: 'images', severity: 'info' }, 'pass', 'All image filenames are descriptive');
         },
     },
     {
@@ -139,15 +215,17 @@ export const imageRules = [
         severity: 'info',
         description: 'Use decoding="async" for non-critical images to improve rendering performance.',
         check: (ctx) => {
-            if (ctx.totalImages === undefined || ctx.totalImages === 0)
-                return null;
-            if (ctx.imagesWithAsyncDecoding === undefined)
-                return null;
+            if (ctx.totalImages === undefined || ctx.totalImages === 0) {
+                return createResult({ id: 'images-decoding-async', name: 'Image Decoding Async', category: 'images', severity: 'info' }, 'info', 'Not applicable (no images detected)', { recommendation: 'This rule checks for async decoding on images for better rendering performance' });
+            }
+            if (ctx.imagesWithAsyncDecoding === undefined) {
+                return createResult({ id: 'images-decoding-async', name: 'Image Decoding Async', category: 'images', severity: 'info' }, 'info', 'Not applicable (async decoding data unavailable)', { recommendation: 'This rule checks for async decoding on images for better rendering performance' });
+            }
             const nonAsync = ctx.totalImages - ctx.imagesWithAsyncDecoding;
             if (nonAsync > 0 && ctx.totalImages > 3) {
                 return createResult({ id: 'images-decoding-async', name: 'Image Decoding Async', category: 'images', severity: 'info' }, 'info', `${nonAsync} image(s) do not use decoding="async"`, { value: nonAsync, recommendation: 'Consider adding decoding="async" to non-critical images for performance benefits.' });
             }
-            return null;
+            return createResult({ id: 'images-decoding-async', name: 'Image Decoding Async', category: 'images', severity: 'info' }, 'pass', 'All images use async decoding or too few images to require it');
         },
     },
     {
@@ -157,8 +235,9 @@ export const imageRules = [
         severity: 'warning',
         description: 'External images should be accessible',
         check: (ctx) => {
-            if (ctx.brokenExternalImages === undefined)
-                return null;
+            if (ctx.brokenExternalImages === undefined) {
+                return createResult({ id: 'broken-external-images', name: 'Broken External Images', category: 'images', severity: 'warning' }, 'info', 'Not applicable (broken external images data unavailable)', { recommendation: 'This rule checks for broken external image references' });
+            }
             if (ctx.brokenExternalImages > 0) {
                 return createResult({ id: 'broken-external-images', name: 'Broken External Images', category: 'images', severity: 'warning' }, 'warn', `${ctx.brokenExternalImages} broken external images`, {
                     value: ctx.brokenExternalImages,
@@ -170,7 +249,7 @@ export const imageRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'broken-external-images', name: 'Broken External Images', category: 'images', severity: 'warning' }, 'pass', 'No broken external images detected');
         },
     },
 ];

package/dist/seo/rules/index.js

@@ -24,6 +24,7 @@ import { resourceRules } from './resources.js';
 import { technicalAdvancedRules } from './technical-advanced.js';
 import { redirectRules } from './redirects.js';
 import { canonicalRules } from './canonical.js';
+import { analyticsRules } from './analytics.js';
 export * from './types.js';
 export * from './thresholds.js';
 export const ALL_SEO_RULES = [
@@ -53,6 +54,7 @@ export const ALL_SEO_RULES = [
     ...technicalAdvancedRules,
     ...redirectRules,
     ...canonicalRules,
+    ...analyticsRules,
 ];
 export const SCORING_WEIGHTS = {
     severity: {