recker 1.0.43 → 1.0.44

package/dist/seo/rules/analytics.js

@@ -0,0 +1,306 @@
+import { createResult } from './types.js';
+export const analyticsRules = [
+    {
+        id: 'analytics-installed',
+        name: 'Analytics Installed',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Page should have analytics tracking installed',
+        check: (ctx) => {
+            if (ctx.analyticsDetected === undefined) {
+                return createResult({ id: 'analytics-installed', name: 'Analytics Installed', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (analytics detection data unavailable)', { recommendation: 'This rule checks for analytics tracking to measure user behavior' });
+            }
+            if (!ctx.analyticsDetected || ctx.analyticsProviders?.length === 0) {
+                return createResult({ id: 'analytics-installed', name: 'Analytics Installed', category: 'technical', severity: 'warning' }, 'warn', 'No analytics tracking detected', {
+                    recommendation: 'Install analytics to understand user behavior and optimize conversions.',
+                    evidence: {
+                        found: 'No analytics scripts detected',
+                        expected: 'Google Analytics, GTM, or other analytics provider',
+                        impact: 'Without analytics, you cannot measure traffic sources, user behavior, conversion rates, or content performance. The average conversion rate is only 2.35% - optimization requires data.',
+                        example: '<!-- Google Analytics 4 -->\n<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>',
+                        learnMore: 'https://marketingplatform.google.com/about/analytics/',
+                    },
+                });
+            }
+            return createResult({ id: 'analytics-installed', name: 'Analytics Installed', category: 'technical', severity: 'warning' }, 'pass', `Analytics detected: ${ctx.analyticsProviders?.join(', ')}`, { value: ctx.analyticsProviders?.join(', ') });
+        },
+    },
+    {
+        id: 'google-analytics-4',
+        name: 'Google Analytics 4',
+        category: 'technical',
+        severity: 'info',
+        description: 'Check for modern GA4 vs deprecated Universal Analytics',
+        check: (ctx) => {
+            if (!ctx.analyticsProviders || ctx.analyticsProviders.length === 0) {
+                return createResult({ id: 'google-analytics-4', name: 'Google Analytics 4', category: 'technical', severity: 'info' }, 'info', 'Not applicable (no analytics providers detected)', { recommendation: 'This rule checks for modern Google Analytics 4 implementation' });
+            }
+            const hasUA = ctx.analyticsProviders.some(p => p === 'Universal Analytics (UA)');
+            const hasGA4 = ctx.analyticsProviders.some(p => p === 'Google Analytics 4 (GA4)');
+            if (hasUA && !hasGA4) {
+                return createResult({ id: 'google-analytics-4', name: 'Google Analytics 4', category: 'technical', severity: 'info' }, 'warn', 'Using deprecated Universal Analytics (UA) without GA4', {
+                    recommendation: 'Migrate to Google Analytics 4 - Universal Analytics stopped processing data July 2023.',
+                    evidence: {
+                        found: 'Universal Analytics (analytics.js or ga.js)',
+                        expected: 'Google Analytics 4 (gtag.js with G-XXXXXX)',
+                        impact: 'Universal Analytics is deprecated and no longer collects data. GA4 offers better cross-platform tracking, machine learning insights, and privacy-focused measurement.',
+                        example: '<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>',
+                        learnMore: 'https://support.google.com/analytics/answer/11583528',
+                    },
+                });
+            }
+            if (hasGA4) {
+                return createResult({ id: 'google-analytics-4', name: 'Google Analytics 4', category: 'technical', severity: 'info' }, 'pass', 'Using modern Google Analytics 4');
+            }
+            return createResult({ id: 'google-analytics-4', name: 'Google Analytics 4', category: 'technical', severity: 'info' }, 'pass', 'Using other analytics provider (not Google Analytics)');
+        },
+    },
+    {
+        id: 'google-tag-manager',
+        name: 'Google Tag Manager',
+        category: 'technical',
+        severity: 'info',
+        description: 'Google Tag Manager enables flexible tag management without code changes',
+        check: (ctx) => {
+            if (!ctx.analyticsProviders) {
+                return createResult({ id: 'google-tag-manager', name: 'Google Tag Manager', category: 'technical', severity: 'info' }, 'info', 'Not applicable (analytics provider data unavailable)', { recommendation: 'This rule checks for Google Tag Manager for easier tag management' });
+            }
+            const hasGTM = ctx.analyticsProviders.some(p => p === 'Google Tag Manager');
+            if (hasGTM) {
+                return createResult({ id: 'google-tag-manager', name: 'Google Tag Manager', category: 'technical', severity: 'info' }, 'pass', 'Google Tag Manager detected', {
+                    evidence: {
+                        found: 'GTM container script',
+                        impact: 'GTM allows marketing teams to manage tags without developer intervention, improving agility.',
+                    },
+                });
+            }
+            if (ctx.analyticsDetected && ctx.analyticsProviders.length > 0) {
+                return createResult({ id: 'google-tag-manager', name: 'Google Tag Manager', category: 'technical', severity: 'info' }, 'info', 'Consider using Google Tag Manager for easier tag management', {
+                    recommendation: 'GTM centralizes all tracking scripts and enables non-developers to manage tags.',
+                    evidence: {
+                        found: `Direct analytics scripts: ${ctx.analyticsProviders.join(', ')}`,
+                        expected: 'Google Tag Manager container managing all tags',
+                        impact: 'GTM provides version control, preview mode, and easy updates without code changes. Best practice for sites with multiple tracking tools.',
+                        learnMore: 'https://tagmanager.google.com/',
+                    },
+                });
+            }
+            return createResult({ id: 'google-tag-manager', name: 'Google Tag Manager', category: 'technical', severity: 'info' }, 'pass', 'No analytics detected or GTM not needed');
+        },
+    },
+    {
+        id: 'multiple-analytics-warning',
+        name: 'Multiple Analytics Scripts',
+        category: 'performance',
+        severity: 'warning',
+        description: 'Too many analytics scripts can impact page performance',
+        check: (ctx) => {
+            if (!ctx.analyticsProviders || ctx.analyticsProviders.length < 4) {
+                return createResult({ id: 'multiple-analytics-warning', name: 'Multiple Analytics Scripts', category: 'performance', severity: 'warning' }, 'info', 'Not applicable (acceptable number of analytics scripts)', { recommendation: 'This rule warns when too many analytics scripts impact performance' });
+            }
+            return createResult({ id: 'multiple-analytics-warning', name: 'Multiple Analytics Scripts', category: 'performance', severity: 'warning' }, 'warn', `${ctx.analyticsProviders.length} analytics scripts detected`, {
+                value: ctx.analyticsProviders.length,
+                recommendation: 'Consolidate analytics tools to reduce page load impact.',
+                evidence: {
+                    found: ctx.analyticsProviders.join(', '),
+                    expected: '1-3 analytics tools',
+                    impact: 'Each analytics script adds HTTP requests, JavaScript execution time, and can slow page rendering. Too many tools can impact Core Web Vitals and user experience.',
+                    learnMore: 'https://web.dev/articles/optimize-third-party-javascript',
+                },
+            });
+        },
+    },
+    {
+        id: 'heatmap-tool',
+        name: 'Heatmap/Session Recording',
+        category: 'technical',
+        severity: 'info',
+        description: 'Heatmap tools like Hotjar help visualize user behavior',
+        check: (ctx) => {
+            if (!ctx.analyticsProviders) {
+                return createResult({ id: 'heatmap-tool', name: 'Heatmap Tool', category: 'technical', severity: 'info' }, 'info', 'Not applicable (analytics provider data unavailable)', { recommendation: 'This rule checks for heatmap and session recording tools' });
+            }
+            const heatmapTools = ['Hotjar', 'Microsoft Clarity', 'FullStory', 'Lucky Orange', 'Crazy Egg'];
+            const foundHeatmap = ctx.analyticsProviders.filter(p => heatmapTools.includes(p));
+            if (foundHeatmap.length > 0) {
+                return createResult({ id: 'heatmap-tool', name: 'Heatmap Tool', category: 'technical', severity: 'info' }, 'pass', `Heatmap/session recording detected: ${foundHeatmap.join(', ')}`, {
+                    evidence: {
+                        found: foundHeatmap.join(', '),
+                        impact: 'Heatmaps and session recordings help identify UX issues, understand user journeys, and optimize conversion paths.',
+                    },
+                });
+            }
+            return createResult({ id: 'heatmap-tool', name: 'Heatmap Tool', category: 'technical', severity: 'info' }, 'pass', 'No heatmap tool detected (optional)');
+        },
+    },
+    {
+        id: 'cta-presence',
+        name: 'Call-to-Action Elements',
+        category: 'content',
+        severity: 'info',
+        description: 'Page should have clear call-to-action elements',
+        check: (ctx) => {
+            if (ctx.ctaButtonsCount === undefined) {
+                return createResult({ id: 'cta-presence', name: 'Call-to-Action Elements', category: 'content', severity: 'info' }, 'info', 'Not applicable (CTA button data unavailable)', { recommendation: 'This rule checks for clear call-to-action elements to guide conversions' });
+            }
+            if (ctx.ctaButtonsCount === 0) {
+                return createResult({ id: 'cta-presence', name: 'Call-to-Action Elements', category: 'content', severity: 'info' }, 'info', 'No clear call-to-action buttons detected', {
+                    recommendation: 'Add clear CTAs to guide users toward conversion.',
+                    evidence: {
+                        found: 'No buttons with action-oriented text',
+                        expected: 'Buttons like "Get Started", "Sign Up", "Buy Now", "Contact Us"',
+                        impact: 'Clear CTAs guide users through the conversion funnel. Pages without obvious next steps lose potential conversions.',
+                        example: '<button class="cta">Get Started Free</button>\n<a href="/signup" class="btn-primary">Start Your Trial</a>',
+                    },
+                });
+            }
+            return createResult({ id: 'cta-presence', name: 'Call-to-Action Elements', category: 'content', severity: 'info' }, 'pass', `${ctx.ctaButtonsCount} call-to-action element(s) found`, { value: ctx.ctaButtonsCount });
+        },
+    },
+    {
+        id: 'form-presence',
+        name: 'Form Elements',
+        category: 'content',
+        severity: 'info',
+        description: 'Detect forms for lead generation or conversion',
+        check: (ctx) => {
+            if (ctx.formCount === undefined) {
+                return createResult({ id: 'form-presence', name: 'Form Elements', category: 'content', severity: 'info' }, 'info', 'Not applicable (form count data unavailable)', { recommendation: 'This rule checks for forms for lead generation and conversions' });
+            }
+            if (ctx.formCount > 0) {
+                return createResult({ id: 'form-presence', name: 'Form Elements', category: 'content', severity: 'info' }, 'pass', `${ctx.formCount} form(s) detected for lead capture/conversion`, {
+                    value: ctx.formCount,
+                    evidence: {
+                        found: `${ctx.formCount} form elements`,
+                        impact: 'Forms are essential for lead generation, contact, and conversions.',
+                    },
+                });
+            }
+            return createResult({ id: 'form-presence', name: 'Form Elements', category: 'content', severity: 'info' }, 'pass', 'No forms detected (may not be needed for this page type)');
+        },
+    },
+    {
+        id: 'contact-methods',
+        name: 'Contact Methods',
+        category: 'content',
+        severity: 'info',
+        description: 'Page should provide contact methods for user trust',
+        check: (ctx) => {
+            const methods = [];
+            if (ctx.emailsFound && ctx.emailsFound.length > 0)
+                methods.push('email');
+            if (ctx.hasPhoneOnPage)
+                methods.push('phone');
+            if (ctx.hasWhatsAppLink)
+                methods.push('WhatsApp');
+            if (methods.length === 0 && ctx.hasContactPageLink) {
+                return createResult({ id: 'contact-methods', name: 'Contact Methods', category: 'content', severity: 'info' }, 'pass', 'Contact page link found', { evidence: { found: 'Link to contact page' } });
+            }
+            if (methods.length > 0) {
+                return createResult({ id: 'contact-methods', name: 'Contact Methods', category: 'content', severity: 'info' }, 'pass', `Contact methods found: ${methods.join(', ')}`, { value: methods.join(', ') });
+            }
+            return createResult({ id: 'contact-methods', name: 'Contact Methods', category: 'content', severity: 'info' }, 'pass', 'No direct contact methods detected (may not be needed)');
+        },
+    },
+    {
+        id: 'rss-feed-present',
+        name: 'RSS Feed',
+        category: 'technical',
+        severity: 'info',
+        description: 'RSS feeds help users and search engines discover new content',
+        check: (ctx) => {
+            if (ctx.hasRssFeed === undefined) {
+                return createResult({ id: 'rss-feed-present', name: 'RSS Feed', category: 'technical', severity: 'info' }, 'info', 'Not applicable (RSS feed data unavailable)', { recommendation: 'This rule checks for RSS feeds for content distribution' });
+            }
+            if (ctx.hasRssFeed) {
+                return createResult({ id: 'rss-feed-present', name: 'RSS Feed', category: 'technical', severity: 'info' }, 'pass', 'RSS feed detected', {
+                    value: ctx.rssFeedUrl,
+                    evidence: {
+                        found: ctx.rssFeedUrl || 'RSS link tag present',
+                        impact: 'RSS feeds notify search engines and feed readers when content is updated, improving content discovery.',
+                    },
+                });
+            }
+            return createResult({ id: 'rss-feed-present', name: 'RSS Feed', category: 'technical', severity: 'info' }, 'info', 'No RSS feed detected', {
+                recommendation: 'Add an RSS feed for blogs or news sites to improve content distribution.',
+                evidence: {
+                    expected: '<link rel="alternate" type="application/rss+xml" href="/feed.xml">',
+                    impact: 'RSS feeds help users subscribe to content and notify search engines of updates. Particularly important for blogs and news sites.',
+                    learnMore: 'https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap#rss-atom',
+                },
+            });
+        },
+    },
+    {
+        id: 'atom-feed-present',
+        name: 'Atom Feed',
+        category: 'technical',
+        severity: 'info',
+        description: 'Atom feeds are an alternative to RSS for content syndication',
+        check: (ctx) => {
+            if (ctx.hasAtomFeed === undefined) {
+                return createResult({ id: 'atom-feed-present', name: 'Atom Feed', category: 'technical', severity: 'info' }, 'info', 'Not applicable (Atom feed data unavailable)', { recommendation: 'This rule checks for Atom feeds as alternative to RSS' });
+            }
+            if (ctx.hasAtomFeed) {
+                return createResult({ id: 'atom-feed-present', name: 'Atom Feed', category: 'technical', severity: 'info' }, 'pass', 'Atom feed detected', {
+                    value: ctx.atomFeedUrl,
+                    evidence: {
+                        found: ctx.atomFeedUrl || 'Atom link tag present',
+                    },
+                });
+            }
+            return createResult({ id: 'atom-feed-present', name: 'Atom Feed', category: 'technical', severity: 'info' }, 'pass', 'No Atom feed detected (RSS is more common)');
+        },
+    },
+    {
+        id: 'noindex-canonical-conflict',
+        name: 'Noindex + Canonical Conflict',
+        category: 'technical',
+        severity: 'error',
+        description: 'Having both noindex and canonical sends conflicting signals',
+        check: (ctx) => {
+            if (!ctx.metaRobots || !ctx.hasCanonical) {
+                return createResult({ id: 'noindex-canonical-conflict', name: 'Noindex + Canonical Conflict', category: 'technical', severity: 'error' }, 'info', 'Not applicable (robots meta tag or canonical data unavailable)', { recommendation: 'This rule detects conflicting noindex and canonical directives' });
+            }
+            const hasNoindex = ctx.metaRobots.includes('noindex');
+            if (hasNoindex && ctx.hasCanonical) {
+                return createResult({ id: 'noindex-canonical-conflict', name: 'Noindex + Canonical Conflict', category: 'technical', severity: 'error' }, 'fail', 'Page has both noindex and canonical - conflicting signals', {
+                    recommendation: 'Remove either noindex or canonical. They serve opposite purposes.',
+                    evidence: {
+                        found: `noindex meta tag + canonical: ${ctx.canonicalUrl}`,
+                        expected: 'Either noindex (to block indexing) OR canonical (to consolidate indexing)',
+                        impact: 'noindex tells search engines not to index this page, while canonical tells them to consolidate signals to a URL. Google may ignore the canonical if noindex is present, wasting crawl budget.',
+                        issue: 'Conflicting indexing directives',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls',
+                    },
+                });
+            }
+            return createResult({ id: 'noindex-canonical-conflict', name: 'Noindex + Canonical Conflict', category: 'technical', severity: 'error' }, 'pass', 'No conflicting noindex and canonical directives');
+        },
+    },
+    {
+        id: 'noindex-sitemap-hint',
+        name: 'Noindex Pages in Sitemap',
+        category: 'crawlability',
+        severity: 'warning',
+        description: 'Pages with noindex should not be in sitemap',
+        check: (ctx) => {
+            if (!ctx.metaRobots) {
+                return createResult({ id: 'noindex-sitemap-hint', name: 'Noindex in Sitemap', category: 'crawlability', severity: 'warning' }, 'info', 'Not applicable (robots meta tag data unavailable)', { recommendation: 'This rule checks if noindex pages are incorrectly included in sitemap' });
+            }
+            const hasNoindex = ctx.metaRobots.includes('noindex');
+            if (hasNoindex && ctx.pageInSitemap) {
+                return createResult({ id: 'noindex-sitemap-hint', name: 'Noindex in Sitemap', category: 'crawlability', severity: 'warning' }, 'warn', 'Page has noindex but appears to be in sitemap', {
+                    recommendation: 'Remove noindex pages from sitemap to avoid wasting crawl budget.',
+                    evidence: {
+                        found: 'noindex directive on page that may be in sitemap',
+                        expected: 'Only indexable pages in sitemap',
+                        impact: 'Including noindex pages in sitemap wastes crawl budget and sends conflicting signals to search engines.',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap#best-practices',
+                    },
+                });
+            }
+            return createResult({ id: 'noindex-sitemap-hint', name: 'Noindex in Sitemap', category: 'crawlability', severity: 'warning' }, 'pass', 'Page is indexable or not in sitemap');
+        },
+    },
+];

package/dist/seo/rules/best-practices.js

@@ -7,8 +7,9 @@ export const bestPracticesRules = [
         severity: 'error',
         description: 'Page must have the HTML doctype',
         check: (ctx) => {
-            if (ctx.hasDoctype === undefined)
-                return null;
+            if (ctx.hasDoctype === undefined) {
+                return createResult({ id: 'bp-doctype', name: 'HTML Doctype', category: 'technical', severity: 'error' }, 'info', 'Unable to check doctype (data unavailable)', { recommendation: 'Ensure HTML content is properly fetched' });
+            }
             if (!ctx.hasDoctype) {
                 return createResult({ id: 'bp-doctype', name: 'HTML Doctype', category: 'technical', severity: 'error' }, 'fail', 'Page is missing HTML doctype', {
                     recommendation: 'Add <!DOCTYPE html> at the start of the document',
@@ -29,8 +30,9 @@ export const bestPracticesRules = [
         severity: 'error',
         description: 'Page should properly define charset',
         check: (ctx) => {
-            if (ctx.hasCharset === undefined)
-                return null;
+            if (ctx.hasCharset === undefined) {
+                return createResult({ id: 'bp-charset', name: 'Character Encoding', category: 'technical', severity: 'error' }, 'info', 'Unable to check charset (data unavailable)', { recommendation: 'Ensure HTML content is properly fetched' });
+            }
             if (!ctx.hasCharset) {
                 return createResult({ id: 'bp-charset', name: 'Character Encoding', category: 'technical', severity: 'error' }, 'fail', 'Page is missing character encoding declaration', {
                     recommendation: 'Add <meta charset="UTF-8"> in the <head>',
@@ -60,8 +62,9 @@ export const bestPracticesRules = [
         severity: 'error',
         description: 'Page should have successful HTTP status code',
         check: (ctx) => {
-            if (ctx.httpStatusCode === undefined)
-                return null;
+            if (ctx.httpStatusCode === undefined) {
+                return createResult({ id: 'bp-http-status', name: 'HTTP Status Code', category: 'technical', severity: 'error' }, 'info', 'Unable to check HTTP status (data unavailable)', { recommendation: 'Ensure the page request completed successfully' });
+            }
             const status = ctx.httpStatusCode;
             if (status >= 400) {
                 return createResult({ id: 'bp-http-status', name: 'HTTP Status Code', category: 'technical', severity: 'error' }, 'fail', `HTTP ${status} error response`, {
@@ -90,8 +93,9 @@ export const bestPracticesRules = [
         severity: 'error',
         description: 'Page should not be blocked from indexing',
         check: (ctx) => {
-            if (ctx.metaRobots === undefined)
-                return null;
+            if (ctx.metaRobots === undefined) {
+                return createResult({ id: 'bp-indexable', name: 'Page Indexable', category: 'technical', severity: 'error' }, 'info', 'Unable to check indexability (no robots meta)', { recommendation: 'Check if the page has robots meta tags' });
+            }
             const robots = Array.isArray(ctx.metaRobots) ? ctx.metaRobots : [ctx.metaRobots];
             const blocked = robots.some(r => r.toLowerCase().includes('noindex') || r.toLowerCase().includes('none'));
             if (blocked) {
@@ -114,8 +118,9 @@ export const bestPracticesRules = [
         severity: 'warning',
         description: 'Links should be crawlable by search engines',
         check: (ctx) => {
-            if (ctx.uncrawlableLinksCount === undefined)
-                return null;
+            if (ctx.uncrawlableLinksCount === undefined) {
+                return createResult({ id: 'bp-links-crawlable', name: 'Crawlable Links', category: 'links', severity: 'warning' }, 'info', 'Unable to check link crawlability (data unavailable)', { recommendation: 'Ensure link analysis completed' });
+            }
             const count = ctx.uncrawlableLinksCount;
             if (count > 0) {
                 return createResult({ id: 'bp-links-crawlable', name: 'Crawlable Links', category: 'links', severity: 'warning' }, 'warn', `${count} link(s) are not crawlable`, {
@@ -139,8 +144,9 @@ export const bestPracticesRules = [
         severity: 'info',
         description: 'robots.txt should be valid and accessible',
         check: (ctx) => {
-            if (ctx.robotsTxtValid === undefined)
-                return null;
+            if (ctx.robotsTxtValid === undefined) {
+                return createResult({ id: 'bp-robots-txt', name: 'Valid robots.txt', category: 'technical', severity: 'info' }, 'info', 'Unable to check robots.txt (data unavailable)', { recommendation: 'Check if robots.txt is accessible at /robots.txt' });
+            }
             if (!ctx.robotsTxtValid) {
                 return createResult({ id: 'bp-robots-txt', name: 'Valid robots.txt', category: 'technical', severity: 'info' }, 'warn', 'robots.txt is invalid or inaccessible', {
                     recommendation: 'Ensure robots.txt is valid and returns 200 status',
@@ -162,8 +168,9 @@ export const bestPracticesRules = [
         severity: 'info',
         description: 'Page should have valid structured data',
         check: (ctx) => {
-            if (ctx.structuredDataErrors === undefined)
-                return null;
+            if (ctx.structuredDataErrors === undefined) {
+                return createResult({ id: 'bp-structured-data', name: 'Structured Data', category: 'structured-data', severity: 'info' }, 'info', 'Unable to check structured data (data unavailable)', { recommendation: 'Ensure JSON-LD structured data analysis completed' });
+            }
             const errors = ctx.structuredDataErrors;
             if (errors > 0) {
                 return createResult({ id: 'bp-structured-data', name: 'Structured Data', category: 'structured-data', severity: 'info' }, 'warn', `${errors} structured data error(s) found`, {

package/dist/seo/rules/canonical.js

@@ -7,14 +7,17 @@ export const canonicalRules = [
         severity: 'warning',
         description: 'Pages should have a canonical URL defined',
         check: (ctx) => {
-            if (ctx.hasCanonical === undefined)
-                return null;
+            if (ctx.hasCanonical === undefined) {
+                return createResult({ id: 'canonical-present', name: 'Canonical Tag Present', category: 'canonicalization', severity: 'warning' }, 'info', 'Not applicable (canonical data unavailable)', { recommendation: 'This rule checks if a canonical URL is defined to avoid duplicate content issues' });
+            }
             if (!ctx.hasCanonical) {
                 return createResult({ id: 'canonical-present', name: 'Canonical Tag Present', category: 'canonicalization', severity: 'warning' }, 'warn', 'Page is missing canonical tag', {
                     recommendation: 'Add <link rel="canonical" href="..."> to specify the preferred URL',
                     evidence: {
+                        found: 'No canonical tag',
                         expected: '<link rel="canonical" href="https://example.com/page">',
-                        impact: 'Without canonical, search engines may index duplicate versions'
+                        impact: 'Without canonical, search engines may index duplicate versions',
+                        example: '<head>\n  <link rel="canonical" href="https://example.com/page" />\n</head>',
                     }
                 });
             }
@@ -28,8 +31,9 @@ export const canonicalRules = [
         severity: 'error',
         description: 'Page should have only one canonical tag',
         check: (ctx) => {
-            if (ctx.canonicalCount === undefined)
-                return null;
+            if (ctx.canonicalCount === undefined) {
+                return createResult({ id: 'canonical-multiple', name: 'Multiple Canonical Tags', category: 'canonicalization', severity: 'error' }, 'info', 'Not applicable (canonical count data unavailable)', { recommendation: 'This rule ensures only one canonical tag exists per page' });
+            }
             if (ctx.canonicalCount > 1) {
                 return createResult({ id: 'canonical-multiple', name: 'Multiple Canonical Tags', category: 'canonicalization', severity: 'error' }, 'fail', `Page has ${ctx.canonicalCount} canonical tags`, {
                     value: ctx.canonicalCount,
@@ -37,11 +41,12 @@ export const canonicalRules = [
                     evidence: {
                         found: ctx.canonicalUrls || [],
                         expected: 'Single canonical tag',
-                        impact: 'Multiple canonicals confuse search engines about preferred URL'
+                        impact: 'Multiple canonicals confuse search engines about preferred URL',
+                        example: '<link rel="canonical" href="https://example.com/page" /> <!-- Keep only one -->',
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'canonical-multiple', name: 'Multiple Canonical Tags', category: 'canonicalization', severity: 'error' }, 'pass', 'Single canonical tag found');
         },
     },
     {
@@ -51,8 +56,9 @@ export const canonicalRules = [
         severity: 'info',
         description: 'Canonical should typically point to the current page URL',
         check: (ctx) => {
-            if (!ctx.canonicalUrl || !ctx.url)
-                return null;
+            if (!ctx.canonicalUrl || !ctx.url) {
+                return createResult({ id: 'canonical-self-referencing', name: 'Canonical Self-Reference', category: 'canonicalization', severity: 'info' }, 'info', 'Not applicable (canonical or URL data unavailable)', { recommendation: 'This rule checks if canonical URL points to the current page' });
+            }
             const isSelfReferencing = normalizeUrl(ctx.canonicalUrl) === normalizeUrl(ctx.url);
             if (!isSelfReferencing) {
                 return createResult({ id: 'canonical-self-referencing', name: 'Canonical Self-Reference', category: 'canonicalization', severity: 'info' }, 'info', 'Canonical points to different URL', {
@@ -60,7 +66,8 @@ export const canonicalRules = [
                     evidence: {
                         found: ctx.canonicalUrl,
                         expected: ctx.url,
-                        impact: 'This page signals to search engines that another URL is preferred'
+                        impact: 'This page signals to search engines that another URL is preferred',
+                        example: `Current URL: ${ctx.url}\nCanonical: ${ctx.canonicalUrl}`,
                     }
                 });
             }
@@ -74,8 +81,9 @@ export const canonicalRules = [
         severity: 'error',
         description: 'Canonical URL should be accessible (not 404)',
         check: (ctx) => {
-            if (ctx.canonicalStatus === undefined)
-                return null;
+            if (ctx.canonicalStatus === undefined) {
+                return createResult({ id: 'canonical-broken', name: 'Broken Canonical URL', category: 'canonicalization', severity: 'error' }, 'info', 'Not applicable (canonical status data unavailable)', { recommendation: 'This rule validates that canonical URL is accessible and returns 200 OK' });
+            }
             if (ctx.canonicalStatus === 404) {
                 return createResult({ id: 'canonical-broken', name: 'Broken Canonical URL', category: 'canonicalization', severity: 'error' }, 'fail', 'Canonical URL returns 404', {
                     value: ctx.canonicalUrl,
@@ -83,7 +91,8 @@ export const canonicalRules = [
                     evidence: {
                         found: `${ctx.canonicalUrl} → 404`,
                         expected: '200 OK',
-                        impact: 'Broken canonical prevents proper indexing'
+                        impact: 'Broken canonical prevents proper indexing',
+                        example: '<link rel="canonical" href="https://example.com/existing-page" />',
                     }
                 });
             }
@@ -94,7 +103,8 @@ export const canonicalRules = [
                     evidence: {
                         found: `${ctx.canonicalUrl} → ${ctx.canonicalStatus}`,
                         expected: '200 OK',
-                        impact: 'Canonical errors prevent proper indexing'
+                        impact: 'Canonical errors prevent proper indexing',
+                        example: '<link rel="canonical" href="https://example.com/accessible-page" />',
                     }
                 });
             }
@@ -105,7 +115,8 @@ export const canonicalRules = [
                     evidence: {
                         found: `${ctx.canonicalUrl} → ${ctx.canonicalFinalUrl}`,
                         expected: 'Direct URL without redirect',
-                        impact: 'Canonical redirects waste crawl budget'
+                        impact: 'Canonical redirects waste crawl budget',
+                        example: `<link rel="canonical" href="${ctx.canonicalFinalUrl}" />`,
                     }
                 });
             }
@@ -119,8 +130,9 @@ export const canonicalRules = [
         severity: 'warning',
         description: 'Canonical should use HTTPS protocol',
         check: (ctx) => {
-            if (!ctx.canonicalUrl)
-                return null;
+            if (!ctx.canonicalUrl) {
+                return createResult({ id: 'canonical-protocol', name: 'Canonical Protocol', category: 'canonicalization', severity: 'warning' }, 'info', 'Not applicable (no canonical URL detected)', { recommendation: 'This rule ensures canonical URLs use HTTPS protocol for security' });
+            }
             if (ctx.canonicalUrl.startsWith('http://')) {
                 return createResult({ id: 'canonical-protocol', name: 'Canonical Protocol', category: 'canonicalization', severity: 'warning' }, 'warn', 'Canonical uses HTTP instead of HTTPS', {
                     value: ctx.canonicalUrl,
@@ -128,7 +140,8 @@ export const canonicalRules = [
                     evidence: {
                         found: ctx.canonicalUrl,
                         expected: ctx.canonicalUrl.replace('http://', 'https://'),
-                        impact: 'HTTP canonicals may cause indexing preference issues'
+                        impact: 'HTTP canonicals may cause indexing preference issues',
+                        example: `<link rel="canonical" href="${ctx.canonicalUrl.replace('http://', 'https://')}" />`,
                     }
                 });
             }
@@ -142,8 +155,9 @@ export const canonicalRules = [
         severity: 'warning',
         description: 'Canonical URL should be absolute, not relative',
         check: (ctx) => {
-            if (!ctx.canonicalUrl)
-                return null;
+            if (!ctx.canonicalUrl) {
+                return createResult({ id: 'canonical-absolute', name: 'Canonical Absolute URL', category: 'canonicalization', severity: 'warning' }, 'info', 'Not applicable (no canonical URL detected)', { recommendation: 'This rule checks that canonical URLs are absolute, not relative' });
+            }
             const isRelative = !ctx.canonicalUrl.startsWith('http://') &&
                 !ctx.canonicalUrl.startsWith('https://') &&
                 !ctx.canonicalUrl.startsWith('//');
@@ -154,7 +168,8 @@ export const canonicalRules = [
                     evidence: {
                         found: ctx.canonicalUrl,
                         expected: 'https://example.com/page',
-                        impact: 'Relative canonicals may be misinterpreted by crawlers'
+                        impact: 'Relative canonicals may be misinterpreted by crawlers',
+                        example: '<link rel="canonical" href="https://example.com/page" />',
                     }
                 });
             }
@@ -168,8 +183,9 @@ export const canonicalRules = [
         severity: 'warning',
         description: 'Canonical should not create chains',
         check: (ctx) => {
-            if (ctx.canonicalChainLength === undefined)
-                return null;
+            if (ctx.canonicalChainLength === undefined) {
+                return createResult({ id: 'canonical-chain', name: 'Canonical Chain', category: 'canonicalization', severity: 'warning' }, 'info', 'Not applicable (canonical chain data unavailable)', { recommendation: 'This rule detects canonical chains where one canonical points to another' });
+            }
             if (ctx.canonicalChainLength > 1) {
                 return createResult({ id: 'canonical-chain', name: 'Canonical Chain', category: 'canonicalization', severity: 'warning' }, 'warn', `Canonical chain detected (${ctx.canonicalChainLength} hops)`, {
                     value: ctx.canonicalChainLength,
@@ -177,11 +193,12 @@ export const canonicalRules = [
                     evidence: {
                         found: ctx.canonicalChain || [],
                         expected: 'Direct canonical to final URL',
-                        impact: 'Canonical chains may cause consolidation issues'
+                        impact: 'Canonical chains may cause consolidation issues',
+                        example: `<link rel="canonical" href="${ctx.canonicalChain?.[ctx.canonicalChain.length - 1] || 'https://example.com/final-page'}" />`,
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'canonical-chain', name: 'Canonical Chain', category: 'canonicalization', severity: 'warning' }, 'pass', 'No canonical chain detected');
         },
     },
     {
@@ -191,8 +208,9 @@ export const canonicalRules = [
         severity: 'info',
         description: 'Canonical URLs with query parameters should be intentional',
         check: (ctx) => {
-            if (!ctx.canonicalUrl)
-                return null;
+            if (!ctx.canonicalUrl) {
+                return createResult({ id: 'canonical-parameters', name: 'Canonical Query Parameters', category: 'canonicalization', severity: 'info' }, 'info', 'Not applicable (no canonical URL detected)', { recommendation: 'This rule checks for query parameters in canonical URLs' });
+            }
             try {
                 const url = new URL(ctx.canonicalUrl);
                 if (url.search && url.search.length > 1) {
@@ -208,7 +226,7 @@ export const canonicalRules = [
             }
             catch {
             }
-            return null;
+            return createResult({ id: 'canonical-parameters', name: 'Canonical Query Parameters', category: 'canonicalization', severity: 'info' }, 'pass', 'Canonical URL has no query parameters');
         },
     },
     {
@@ -218,8 +236,9 @@ export const canonicalRules = [
         severity: 'warning',
         description: 'Pages with noindex should not have canonical to indexed page',
         check: (ctx) => {
-            if (!ctx.hasCanonical || ctx.metaRobots === undefined)
-                return null;
+            if (!ctx.hasCanonical || ctx.metaRobots === undefined) {
+                return createResult({ id: 'canonical-noindex-conflict', name: 'Canonical + Noindex Conflict', category: 'canonicalization', severity: 'warning' }, 'info', 'Not applicable (canonical or robots meta tag data unavailable)', { recommendation: 'This rule detects conflicting noindex and canonical directives' });
+            }
             const robots = Array.isArray(ctx.metaRobots) ? ctx.metaRobots : [ctx.metaRobots];
             const hasNoindex = robots.some(r => r.toLowerCase().includes('noindex'));
             if (hasNoindex && ctx.canonicalUrl) {
@@ -229,12 +248,14 @@ export const canonicalRules = [
                         recommendation: 'Remove canonical or noindex - conflicting signals',
                         evidence: {
                             found: `noindex + canonical to self (${ctx.canonicalUrl})`,
-                            impact: 'Google ignores noindex if page has canonical to itself'
+                            expected: 'Either noindex OR canonical, not both',
+                            impact: 'Google ignores noindex if page has canonical to itself',
+                            example: '<meta name="robots" content="noindex" /> <!-- Remove this -->\n<!-- OR -->\n<link rel="canonical" href="..." /> <!-- Remove this -->',
                         }
                     });
                 }
             }
-            return null;
+            return createResult({ id: 'canonical-noindex-conflict', name: 'Canonical + Noindex Conflict', category: 'canonicalization', severity: 'warning' }, 'pass', 'No conflicting noindex and canonical directives');
         },
     },
 ];