recker 1.0.42 → 1.0.43-next.7a08602

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;
@@ -111,7 +156,7 @@ export const imageRules = [
             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 +166,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 +195,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 +215,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 +229,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: {

package/dist/seo/rules/internal-linking.js

@@ -7,8 +7,9 @@ export const internalLinkingRules = [
         severity: 'warning',
         description: 'Pages should have a healthy number of internal links',
         check: (ctx) => {
-            if (ctx.internalLinks === undefined)
-                return null;
+            if (ctx.internalLinks === undefined) {
+                return createResult({ id: 'linking-internal-count', name: 'Internal Link Count', category: 'links', severity: 'warning' }, 'info', 'Not applicable (internal links data unavailable)', { recommendation: 'This rule checks internal link count to ensure proper site navigation and link equity distribution' });
+            }
             const count = ctx.internalLinks;
             if (count === 0) {
                 return createResult({ id: 'linking-internal-count', name: 'Internal Link Count', category: 'links', severity: 'warning' }, 'warn', 'No internal links found', {
@@ -39,10 +40,12 @@ export const internalLinkingRules = [
         severity: 'info',
         description: 'Pages should have more internal than external links',
         check: (ctx) => {
-            if (ctx.internalLinks === undefined || ctx.externalLinks === undefined)
-                return null;
-            if (ctx.totalLinks === undefined || ctx.totalLinks === 0)
-                return null;
+            if (ctx.internalLinks === undefined || ctx.externalLinks === undefined) {
+                return createResult({ id: 'linking-internal-ratio', name: 'Internal/External Link Ratio', category: 'links', severity: 'info' }, 'info', 'Not applicable (link data unavailable)', { recommendation: 'This rule checks the balance between internal and external links' });
+            }
+            if (ctx.totalLinks === undefined || ctx.totalLinks === 0) {
+                return createResult({ id: 'linking-internal-ratio', name: 'Internal/External Link Ratio', category: 'links', severity: 'info' }, 'info', 'Not applicable (no links detected)', { recommendation: 'This rule requires at least some links to analyze the internal/external ratio' });
+            }
             const internal = ctx.internalLinks;
             const external = ctx.externalLinks;
             const ratio = internal / (external || 1);
@@ -66,11 +69,13 @@ export const internalLinkingRules = [
         severity: 'info',
         description: 'Internal links should use diverse, descriptive anchor text',
         check: (ctx) => {
-            if (!ctx.allLinks || ctx.allLinks.length === 0)
-                return null;
+            if (!ctx.allLinks || ctx.allLinks.length === 0) {
+                return createResult({ id: 'linking-anchor-diversity', name: 'Anchor Text Diversity', category: 'links', severity: 'info' }, 'info', 'Not applicable (no links detected)', { recommendation: 'This rule checks anchor text diversity to prevent over-optimization' });
+            }
             const internalLinks = ctx.allLinks.filter(l => l.type === 'internal');
-            if (internalLinks.length < 3)
-                return null;
+            if (internalLinks.length < 3) {
+                return createResult({ id: 'linking-anchor-diversity', name: 'Anchor Text Diversity', category: 'links', severity: 'info' }, 'info', 'Not applicable (insufficient internal links)', { recommendation: 'This rule requires at least 3 internal links to analyze anchor text diversity' });
+            }
             const anchorCounts = {};
             for (const link of internalLinks) {
                 const anchor = (link.text || '').toLowerCase().trim();
@@ -100,11 +105,13 @@ export const internalLinkingRules = [
         severity: 'info',
         description: 'Pages should link to deep content, not just homepage',
         check: (ctx) => {
-            if (!ctx.allLinks || ctx.allLinks.length === 0)
-                return null;
+            if (!ctx.allLinks || ctx.allLinks.length === 0) {
+                return createResult({ id: 'linking-deep-links', name: 'Deep Linking', category: 'links', severity: 'info' }, 'info', 'Not applicable (no links detected)', { recommendation: 'This rule checks for deep linking patterns to ensure inner pages are properly linked' });
+            }
             const internalLinks = ctx.allLinks.filter(l => l.type === 'internal');
-            if (internalLinks.length === 0)
-                return null;
+            if (internalLinks.length === 0) {
+                return createResult({ id: 'linking-deep-links', name: 'Deep Linking', category: 'links', severity: 'info' }, 'info', 'Not applicable (no internal links detected)', { recommendation: 'This rule requires internal links to analyze deep linking patterns' });
+            }
             let rootLinks = 0;
             let deepLinks = 0;
             for (const link of internalLinks) {
@@ -142,10 +149,12 @@ export const internalLinkingRules = [
         severity: 'info',
         description: 'Check for proper navigation link structure',
         check: (ctx) => {
-            if (!ctx.hasNav)
-                return null;
-            if (ctx.navLinkCount === undefined)
-                return null;
+            if (!ctx.hasNav) {
+                return createResult({ id: 'linking-nav-links', name: 'Navigation Links', category: 'links', severity: 'info' }, 'info', 'Not applicable (no navigation element detected)', { recommendation: 'This rule checks navigation link structure when a <nav> element is present' });
+            }
+            if (ctx.navLinkCount === undefined) {
+                return createResult({ id: 'linking-nav-links', name: 'Navigation Links', category: 'links', severity: 'info' }, 'info', 'Not applicable (navigation link count unavailable)', { recommendation: 'This rule checks the number of links in navigation elements' });
+            }
             if (ctx.navLinkCount === 0) {
                 return createResult({ id: 'linking-nav-links', name: 'Navigation Links', category: 'links', severity: 'info' }, 'warn', 'Navigation element has no links', {
                     recommendation: 'Add links to navigation for user experience and SEO',
@@ -175,10 +184,12 @@ export const internalLinkingRules = [
         severity: 'info',
         description: 'Footer should contain important site-wide links',
         check: (ctx) => {
-            if (!ctx.hasFooter)
-                return null;
-            if (ctx.footerLinkCount === undefined)
-                return null;
+            if (!ctx.hasFooter) {
+                return createResult({ id: 'linking-footer-links', name: 'Footer Links', category: 'links', severity: 'info' }, 'info', 'Not applicable (no footer element detected)', { recommendation: 'This rule checks footer link structure when a <footer> element is present' });
+            }
+            if (ctx.footerLinkCount === undefined) {
+                return createResult({ id: 'linking-footer-links', name: 'Footer Links', category: 'links', severity: 'info' }, 'info', 'Not applicable (footer link count unavailable)', { recommendation: 'This rule checks the number of links in footer elements' });
+            }
             if (ctx.footerLinkCount === 0) {
                 return createResult({ id: 'linking-footer-links', name: 'Footer Links', category: 'links', severity: 'info' }, 'info', 'Footer has no links', {
                     recommendation: 'Add important links to footer',
@@ -206,10 +217,12 @@ export const internalLinkingRules = [
         severity: 'info',
         description: 'Check for in-content contextual links',
         check: (ctx) => {
-            if (ctx.contextualLinkCount === undefined)
-                return null;
-            if (!ctx.wordCount || ctx.wordCount < 300)
-                return null;
+            if (ctx.contextualLinkCount === undefined) {
+                return createResult({ id: 'linking-contextual', name: 'Contextual Links', category: 'links', severity: 'info' }, 'info', 'Not applicable (contextual link count unavailable)', { recommendation: 'This rule checks for in-content contextual links that pass more link equity' });
+            }
+            if (!ctx.wordCount || ctx.wordCount < 300) {
+                return createResult({ id: 'linking-contextual', name: 'Contextual Links', category: 'links', severity: 'info' }, 'info', 'Not applicable (insufficient content for contextual link analysis)', { recommendation: 'This rule requires at least 300 words to analyze contextual link patterns' });
+            }
             const count = ctx.contextualLinkCount;
             if (count === 0) {
                 return createResult({ id: 'linking-contextual', name: 'Contextual Links', category: 'links', severity: 'info' }, 'info', 'No contextual links in content', {
@@ -240,8 +253,9 @@ export const internalLinkingRules = [
         severity: 'warning',
         description: 'Pages should be linked from other pages on the site',
         check: (ctx) => {
-            if (ctx.incomingInternalLinks === undefined)
-                return null;
+            if (ctx.incomingInternalLinks === undefined) {
+                return createResult({ id: 'linking-orphan-page', name: 'Orphan Page Detection', category: 'links', severity: 'warning' }, 'info', 'Not applicable (incoming internal links data unavailable)', { recommendation: 'This rule checks if pages receive incoming internal links to prevent orphan pages' });
+            }
             if (ctx.incomingInternalLinks === 0) {
                 return createResult({ id: 'linking-orphan-page', name: 'Orphan Page Detection', category: 'links', severity: 'warning' }, 'warn', 'Page may be an orphan (no incoming internal links)', {
                     recommendation: 'Link to this page from other pages on your site',
@@ -262,8 +276,9 @@ export const internalLinkingRules = [
         severity: 'info',
         description: 'Avoid excessive self-referencing links',
         check: (ctx) => {
-            if (ctx.selfReferencingLinks === undefined)
-                return null;
+            if (ctx.selfReferencingLinks === undefined) {
+                return createResult({ id: 'linking-self-referencing', name: 'Self-Referencing Links', category: 'links', severity: 'info' }, 'info', 'Not applicable (self-referencing links data unavailable)', { recommendation: 'This rule checks for excessive self-referencing links that waste crawl budget' });
+            }
             if (ctx.selfReferencingLinks > 3) {
                 return createResult({ id: 'linking-self-referencing', name: 'Self-Referencing Links', category: 'links', severity: 'info' }, 'info', `${ctx.selfReferencingLinks} self-referencing links`, {
                     recommendation: 'Reduce links that point to the current page',
@@ -274,7 +289,7 @@ export const internalLinkingRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'linking-self-referencing', name: 'Self-Referencing Links', category: 'links', severity: 'info' }, 'info', 'Not applicable (acceptable self-referencing link count)', { recommendation: 'Self-referencing links are acceptable at current level (0-3 links)' });
         },
     },
     {
@@ -284,8 +299,9 @@ export const internalLinkingRules = [
         severity: 'error',
         description: 'Internal links should not be broken',
         check: (ctx) => {
-            if (ctx.brokenInternalLinks === undefined)
-                return null;
+            if (ctx.brokenInternalLinks === undefined) {
+                return createResult({ id: 'linking-broken-internal', name: 'Broken Internal Links', category: 'links', severity: 'error' }, 'info', 'Not applicable (broken internal links data unavailable)', { recommendation: 'This rule checks for broken internal links that harm user experience and waste crawl budget' });
+            }
             if (ctx.brokenInternalLinks.length > 0) {
                 return createResult({ id: 'linking-broken-internal', name: 'Broken Internal Links', category: 'links', severity: 'error' }, 'fail', `${ctx.brokenInternalLinks.length} broken internal link(s)`, {
                     recommendation: 'Fix or remove broken internal links',
@@ -306,8 +322,9 @@ export const internalLinkingRules = [
         severity: 'warning',
         description: 'Internal links should not go through redirect chains',
         check: (ctx) => {
-            if (ctx.redirectChainLinks === undefined)
-                return null;
+            if (ctx.redirectChainLinks === undefined) {
+                return createResult({ id: 'linking-redirect-chains', name: 'Redirect Chains', category: 'links', severity: 'warning' }, 'info', 'Not applicable (redirect chain data unavailable)', { recommendation: 'This rule checks for redirect chains that slow crawling and lose link equity' });
+            }
             if (ctx.redirectChainLinks.length > 0) {
                 return createResult({ id: 'linking-redirect-chains', name: 'Redirect Chains', category: 'links', severity: 'warning' }, 'warn', `${ctx.redirectChainLinks.length} link(s) go through redirects`, {
                     recommendation: 'Update links to point to final destination URLs',
@@ -328,8 +345,9 @@ export const internalLinkingRules = [
         severity: 'warning',
         description: 'Internal links should not use nofollow',
         check: (ctx) => {
-            if (!ctx.allLinks)
-                return null;
+            if (!ctx.allLinks) {
+                return createResult({ id: 'linking-nofollow-internal', name: 'Nofollow Internal Links', category: 'links', severity: 'warning' }, 'info', 'Not applicable (links data unavailable)', { recommendation: 'This rule checks for nofollow attributes on internal links which waste PageRank' });
+            }
             const nofollowInternal = ctx.allLinks.filter(l => l.type === 'internal' && l.rel?.includes('nofollow'));
             if (nofollowInternal.length > 0) {
                 return createResult({ id: 'linking-nofollow-internal', name: 'Nofollow Internal Links', category: 'links', severity: 'warning' }, 'warn', `${nofollowInternal.length} internal link(s) have nofollow`, {
@@ -351,8 +369,9 @@ export const internalLinkingRules = [
         severity: 'info',
         description: 'Important pages should be reachable in few clicks',
         check: (ctx) => {
-            if (ctx.pageClickDepth === undefined)
-                return null;
+            if (ctx.pageClickDepth === undefined) {
+                return createResult({ id: 'linking-click-depth', name: 'Click Depth', category: 'links', severity: 'info' }, 'info', 'Not applicable (click depth data unavailable)', { recommendation: 'This rule checks how many clicks from homepage, affecting crawl priority and link equity' });
+            }
             const depth = ctx.pageClickDepth;
             if (depth > 4) {
                 return createResult({ id: 'linking-click-depth', name: 'Click Depth', category: 'links', severity: 'info' }, 'warn', `Page is ${depth} clicks from homepage`, {