recker 1.0.43 → 1.0.44

package/dist/seo/rules/meta.js

@@ -19,7 +19,7 @@ export const metaRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'title-exists', name: 'Title Tag Exists', category: 'title', severity: 'error' }, 'info', 'Not applicable (page has title tag)', { recommendation: 'This rule checks for the presence of a title tag' });
         },
     },
     {
@@ -29,15 +29,32 @@ export const metaRules = [
         severity: 'warning',
         description: 'Title should be between 50-60 characters',
         check: (ctx) => {
-            if (!ctx.title)
-                return null;
+            if (!ctx.title) {
+                return createResult({ id: 'title-length', name: 'Title Length', category: 'title', severity: 'warning' }, 'info', 'Not applicable (no title tag)', { recommendation: 'This rule checks title length when a title tag is present' });
+            }
             const len = ctx.titleLength ?? ctx.title.length;
             const { min, ideal, max } = SEO_THRESHOLDS.title;
             if (len < min) {
-                return createResult({ id: 'title-length', name: 'Title Length', category: 'title', severity: 'warning' }, 'warn', `Title too short (${len} chars, min: ${min})`, { value: len, recommendation: `Expand title to ${ideal.min}-${ideal.max} characters` });
+                return createResult({ id: 'title-length', name: 'Title Length', category: 'title', severity: 'warning' }, 'warn', `Title too short (${len} chars, min: ${min})`, {
+                    value: len,
+                    recommendation: `Expand title to ${ideal.min}-${ideal.max} characters. Ensure it includes target keywords and encourages clicks.`,
+                    evidence: {
+                        found: `${len} characters`,
+                        expected: `${ideal.min}-${ideal.max} characters`,
+                        impact: 'Short titles limit keyword potential and may be replaced by Google.'
+                    }
+                });
             }
             if (len > max) {
-                return createResult({ id: 'title-length', name: 'Title Length', category: 'title', severity: 'warning' }, 'warn', `Title too long (${len} chars, will be truncated after ~60)`, { value: len, recommendation: `Shorten title to under ${ideal.max} characters` });
+                return createResult({ id: 'title-length', name: 'Title Length', category: 'title', severity: 'warning' }, 'warn', `Title too long (${len} chars, will be truncated after ~60)`, {
+                    value: len,
+                    recommendation: `Shorten title to under ${ideal.max} characters to ensure visibility in SERPs.`,
+                    evidence: {
+                        found: `${len} characters`,
+                        expected: `< ${max} characters`,
+                        impact: 'Truncated titles may lose click-through rate if key information is hidden.'
+                    }
+                });
             }
             if (len >= ideal.min && len <= ideal.max) {
                 return createResult({ id: 'title-length', name: 'Title Length', category: 'title', severity: 'warning' }, 'pass', `Title length ideal (${len} chars)`, { value: len });
@@ -52,14 +69,23 @@ export const metaRules = [
         severity: 'warning',
         description: 'Title should not be ALL CAPS',
         check: (ctx) => {
-            if (!ctx.title)
-                return null;
+            if (!ctx.title) {
+                return createResult({ id: 'title-no-caps', name: 'Title Case', category: 'title', severity: 'warning' }, 'info', 'Not applicable (no title tag)', { recommendation: 'This rule checks title capitalization when a title tag is present' });
+            }
             const words = ctx.title.split(/\s+/).filter((w) => w.length > 3);
             const allCapsWords = words.filter((w) => w === w.toUpperCase() && /[A-Z]/.test(w));
             if (allCapsWords.length > words.length / 2) {
-                return createResult({ id: 'title-no-caps', name: 'Title Case', category: 'title', severity: 'warning' }, 'warn', 'Title appears to be ALL CAPS', { recommendation: 'Use title case or sentence case for better readability' });
+                return createResult({ id: 'title-no-caps', name: 'Title Case', category: 'title', severity: 'warning' }, 'warn', 'Title appears to be ALL CAPS', {
+                    recommendation: 'Use title case or sentence case for better readability and click-through rate.',
+                    evidence: {
+                        found: ctx.title,
+                        expected: 'Normal capitalization (Title Case or Sentence case)',
+                        impact: 'ALL CAPS titles look spammy and may be ignored by users. Google may also rewrite them.',
+                        example: 'Instead of "BUY SHOES ONLINE NOW", use "Buy Shoes Online - Free Shipping"'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'title-no-caps', name: 'Title Case', category: 'title', severity: 'warning' }, 'info', 'Not applicable (title uses proper capitalization)', { recommendation: 'This rule checks for excessive ALL CAPS usage in title' });
         },
     },
     {
@@ -69,14 +95,23 @@ export const metaRules = [
         severity: 'warning',
         description: 'Title and H1 should be similar but not identical',
         check: (ctx) => {
-            if (!ctx.title || !ctx.h1Text)
-                return null;
+            if (!ctx.title || !ctx.h1Text) {
+                return createResult({ id: 'title-h1-different', name: 'Title vs H1', category: 'title', severity: 'warning' }, 'info', 'Not applicable (missing title or H1)', { recommendation: 'This rule compares title and H1 when both are present' });
+            }
             const titleNorm = ctx.title.toLowerCase().trim();
             const h1Norm = ctx.h1Text.toLowerCase().trim();
             if (titleNorm === h1Norm) {
-                return createResult({ id: 'title-h1-different', name: 'Title vs H1', category: 'title', severity: 'warning' }, 'warn', 'Title and H1 are identical', { recommendation: 'Consider making H1 slightly different from title for variety' });
+                return createResult({ id: 'title-h1-different', name: 'Title vs H1', category: 'title', severity: 'warning' }, 'warn', 'Title and H1 are identical', {
+                    recommendation: 'Consider making H1 slightly different from title for variety',
+                    evidence: {
+                        found: `Both are: "${ctx.title}"`,
+                        expected: 'Similar but not identical text (variation helps SEO)',
+                        impact: 'Identical title and H1 waste an opportunity to include related keywords and may appear redundant',
+                        example: 'Title: "Buy Running Shoes Online - Free Shipping"\nH1: "Best Running Shoes - Shop Now"'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'title-h1-different', name: 'Title vs H1', category: 'title', severity: 'warning' }, 'info', 'Not applicable (title and H1 are different)', { recommendation: 'This rule checks if title and H1 are identical' });
         },
     },
     {
@@ -97,7 +132,7 @@ export const metaRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'meta-description-exists', name: 'Meta Description Exists', category: 'meta', severity: 'error' }, 'info', 'Not applicable (page has meta description)', { recommendation: 'This rule checks for the presence of a meta description' });
         },
     },
     {
@@ -107,15 +142,32 @@ export const metaRules = [
         severity: 'warning',
         description: 'Meta description should be 120-155 characters',
         check: (ctx) => {
-            if (!ctx.metaDescription)
-                return null;
+            if (!ctx.metaDescription) {
+                return createResult({ id: 'meta-description-length', name: 'Meta Description Length', category: 'meta', severity: 'warning' }, 'info', 'Not applicable (no meta description)', { recommendation: 'This rule checks meta description length when present' });
+            }
             const len = ctx.metaDescriptionLength ?? ctx.metaDescription.length;
             const { min, ideal, max } = SEO_THRESHOLDS.metaDescription;
             if (len < min) {
-                return createResult({ id: 'meta-description-length', name: 'Meta Description Length', category: 'meta', severity: 'warning' }, 'warn', `Description too short (${len} chars, min: ${min})`, { value: len, recommendation: `Expand to ${ideal.min}-${ideal.max} characters` });
+                return createResult({ id: 'meta-description-length', name: 'Meta Description Length', category: 'meta', severity: 'warning' }, 'warn', `Description too short (${len} chars, min: ${min})`, {
+                    value: len,
+                    recommendation: `Expand to ${ideal.min}-${ideal.max} characters. Summarize content and include keywords naturally.`,
+                    evidence: {
+                        found: `${len} characters`,
+                        expected: `${ideal.min}-${ideal.max} characters`,
+                        impact: 'Short descriptions may be ignored by search engines in favor of auto-generated snippets.'
+                    }
+                });
             }
             if (len > max) {
-                return createResult({ id: 'meta-description-length', name: 'Meta Description Length', category: 'meta', severity: 'warning' }, 'warn', `Description may be truncated (${len} chars, max: ${max})`, { value: len, recommendation: `Shorten to under ${max} characters` });
+                return createResult({ id: 'meta-description-length', name: 'Meta Description Length', category: 'meta', severity: 'warning' }, 'warn', `Description may be truncated (${len} chars, max: ${max})`, {
+                    value: len,
+                    recommendation: `Shorten to under ${max} characters. Ensure the most important info is at the start.`,
+                    evidence: {
+                        found: `${len} characters`,
+                        expected: `< ${max} characters`,
+                        impact: 'Truncated descriptions look unprofessional and may lower CTR.'
+                    }
+                });
             }
             if (len >= ideal.min && len <= ideal.max) {
                 return createResult({ id: 'meta-description-length', name: 'Meta Description Length', category: 'meta', severity: 'warning' }, 'pass', `Description length ideal (${len} chars)`, { value: len });
@@ -130,16 +182,25 @@ export const metaRules = [
         severity: 'info',
         description: 'Meta description should be unique and compelling',
         check: (ctx) => {
-            if (!ctx.metaDescription)
-                return null;
+            if (!ctx.metaDescription) {
+                return createResult({ id: 'meta-description-unique', name: 'Description Quality', category: 'meta', severity: 'info' }, 'info', 'Not applicable (no meta description)', { recommendation: 'This rule checks meta description quality when present' });
+            }
             const desc = ctx.metaDescription.toLowerCase();
             const placeholders = ['lorem ipsum', 'description here', 'todo', 'placeholder', 'change this'];
             for (const placeholder of placeholders) {
                 if (desc.includes(placeholder)) {
-                    return createResult({ id: 'meta-description-unique', name: 'Description Quality', category: 'meta', severity: 'info' }, 'warn', 'Meta description appears to be a placeholder', { recommendation: 'Replace with a unique, compelling description for better CTR' });
+                    return createResult({ id: 'meta-description-unique', name: 'Description Quality', category: 'meta', severity: 'info' }, 'warn', 'Meta description appears to be a placeholder', {
+                        recommendation: 'Replace with a unique, compelling description for better CTR',
+                        evidence: {
+                            found: `Contains placeholder text: "${placeholder}"`,
+                            expected: 'Unique, compelling description that summarizes page content',
+                            impact: 'Placeholder text looks unprofessional and will hurt click-through rates in search results',
+                            example: 'Instead of "Description here", use "Shop premium running shoes with free shipping on orders over $50. 30-day returns."'
+                        }
+                    });
                 }
             }
-            return null;
+            return createResult({ id: 'meta-description-unique', name: 'Description Quality', category: 'meta', severity: 'info' }, 'info', 'Not applicable (description has good quality)', { recommendation: 'This rule checks for placeholder patterns in meta description' });
         },
     },
     {
@@ -160,7 +221,7 @@ export const metaRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'og-title-exists', name: 'OG Title Exists', category: 'og', severity: 'error' }, 'info', 'Not applicable (page has og:title)', { recommendation: 'This rule checks for the presence of og:title meta tag' });
         },
     },
     {
@@ -170,12 +231,22 @@ export const metaRules = [
         severity: 'warning',
         description: 'og:title should be 60-70 characters (max 90)',
         check: (ctx) => {
-            if (!ctx.ogTitle)
-                return null;
+            if (!ctx.ogTitle) {
+                return createResult({ id: 'og-title-length', name: 'OG Title Length', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:title)', { recommendation: 'This rule checks og:title length when present' });
+            }
             const len = ctx.ogTitle.length;
             const { ideal, max } = SEO_THRESHOLDS.og.title;
             if (len > max) {
-                return createResult({ id: 'og-title-length', name: 'OG Title Length', category: 'og', severity: 'warning' }, 'warn', `og:title too long (${len} chars, truncates at ~${max})`, { value: len, recommendation: `Shorten to ${ideal.max} characters` });
+                return createResult({ id: 'og-title-length', name: 'OG Title Length', category: 'og', severity: 'warning' }, 'warn', `og:title too long (${len} chars, truncates at ~${max})`, {
+                    value: len,
+                    recommendation: `Shorten to ${ideal.max} characters`,
+                    evidence: {
+                        found: `${len} characters`,
+                        expected: `${ideal.min}-${ideal.max} characters (max ${max})`,
+                        impact: 'Long titles get truncated on Facebook, LinkedIn, and other platforms, potentially hiding key information',
+                        example: 'Instead of a 100-char title, use "Amazing Product - 50% Off Today | YourBrand" (48 chars)'
+                    }
+                });
             }
             if (len >= ideal.min && len <= ideal.max) {
                 return createResult({ id: 'og-title-length', name: 'OG Title Length', category: 'og', severity: 'warning' }, 'pass', `og:title length ideal (${len} chars)`, { value: len });
@@ -190,13 +261,22 @@ export const metaRules = [
         severity: 'warning',
         description: 'og:title should not contain emojis (some networks remove them)',
         check: (ctx) => {
-            if (!ctx.ogTitle)
-                return null;
+            if (!ctx.ogTitle) {
+                return createResult({ id: 'og-title-no-emoji', name: 'OG Title No Emoji', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:title)', { recommendation: 'This rule checks for emojis in og:title when present' });
+            }
             const emojiRegex = /[\u{1F300}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]/u;
             if (emojiRegex.test(ctx.ogTitle)) {
-                return createResult({ id: 'og-title-no-emoji', name: 'OG Title Emoji', category: 'og', severity: 'warning' }, 'warn', 'og:title contains emojis (some networks remove them)', { recommendation: 'Remove emojis from og:title for consistent display' });
+                return createResult({ id: 'og-title-no-emoji', name: 'OG Title Emoji', category: 'og', severity: 'warning' }, 'warn', 'og:title contains emojis (some networks remove them)', {
+                    recommendation: 'Remove emojis from og:title for consistent display',
+                    evidence: {
+                        found: `Title contains emojis: "${ctx.ogTitle}"`,
+                        expected: 'Text without emoji characters',
+                        impact: 'Facebook, LinkedIn, and some other platforms strip emojis from titles, causing inconsistent display',
+                        example: 'Instead of "🚀 Amazing Product", use "Amazing Product - Fast Delivery"'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'og-title-no-emoji', name: 'OG Title No Emoji', category: 'og', severity: 'warning' }, 'info', 'Not applicable (og:title has no emojis)', { recommendation: 'This rule checks for emoji characters in og:title' });
         },
     },
     {
@@ -217,7 +297,7 @@ export const metaRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'og-description-exists', name: 'OG Description Exists', category: 'og', severity: 'error' }, 'info', 'Not applicable (page has og:description)', { recommendation: 'This rule checks for the presence of og:description meta tag' });
         },
     },
     {
@@ -227,12 +307,22 @@ export const metaRules = [
         severity: 'warning',
         description: 'og:description should be 110-155 characters (max 200)',
         check: (ctx) => {
-            if (!ctx.ogDescription)
-                return null;
+            if (!ctx.ogDescription) {
+                return createResult({ id: 'og-description-length', name: 'OG Description Length', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:description)', { recommendation: 'This rule checks og:description length when present' });
+            }
             const len = ctx.ogDescription.length;
             const { ideal, max } = SEO_THRESHOLDS.og.description;
             if (len > max) {
-                return createResult({ id: 'og-description-length', name: 'OG Description Length', category: 'og', severity: 'warning' }, 'warn', `og:description too long (${len} chars, truncates at ~${max})`, { value: len, recommendation: `Shorten to ${ideal.max} characters` });
+                return createResult({ id: 'og-description-length', name: 'OG Description Length', category: 'og', severity: 'warning' }, 'warn', `og:description too long (${len} chars, truncates at ~${max})`, {
+                    value: len,
+                    recommendation: `Shorten to ${ideal.max} characters`,
+                    evidence: {
+                        found: `${len} characters`,
+                        expected: `${ideal.min}-${ideal.max} characters (max ${max})`,
+                        impact: 'Descriptions longer than 200 chars get truncated on social platforms, hiding important information',
+                        example: 'Keep description concise: "Shop premium running shoes. Free shipping over $50. 30-day returns." (85 chars)'
+                    }
+                });
             }
             if (len >= ideal.min && len <= ideal.max) {
                 return createResult({ id: 'og-description-length', name: 'OG Description Length', category: 'og', severity: 'warning' }, 'pass', `og:description length ideal (${len} chars)`, { value: len });
@@ -259,7 +349,7 @@ export const metaRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'og-image-exists', name: 'OG Image Exists', category: 'og', severity: 'error' }, 'info', 'Not applicable (page has og:image)', { recommendation: 'This rule checks for the presence of og:image meta tag' });
         },
     },
     {
@@ -269,10 +359,20 @@ export const metaRules = [
         severity: 'error',
         description: 'og:image URL must use HTTPS',
         check: (ctx) => {
-            if (!ctx.ogImage)
-                return null;
+            if (!ctx.ogImage) {
+                return createResult({ id: 'og-image-https', name: 'OG Image HTTPS', category: 'og', severity: 'error' }, 'info', 'Not applicable (no og:image)', { recommendation: 'This rule checks og:image URL protocol when present' });
+            }
             if (ctx.ogImage.startsWith('http://')) {
-                return createResult({ id: 'og-image-https', name: 'OG Image HTTPS', category: 'og', severity: 'error' }, 'fail', 'og:image uses HTTP instead of HTTPS', { value: ctx.ogImage, recommendation: 'Always use HTTPS for og:image URLs' });
+                return createResult({ id: 'og-image-https', name: 'OG Image HTTPS', category: 'og', severity: 'error' }, 'fail', 'og:image uses HTTP instead of HTTPS', {
+                    value: ctx.ogImage,
+                    recommendation: 'Always use HTTPS for og:image URLs',
+                    evidence: {
+                        found: `HTTP URL: ${ctx.ogImage}`,
+                        expected: 'HTTPS URL (https://...)',
+                        impact: 'Facebook and other platforms may block HTTP images due to mixed content security policies',
+                        example: `Change http://yoursite.com/image.jpg to https://yoursite.com/image.jpg`
+                    }
+                });
             }
             return createResult({ id: 'og-image-https', name: 'OG Image HTTPS', category: 'og', severity: 'error' }, 'pass', 'og:image uses HTTPS');
         },
@@ -285,7 +385,15 @@ export const metaRules = [
         description: 'og:url should be defined (canonical URL for sharing)',
         check: (ctx) => {
             if (!ctx.ogUrl) {
-                return createResult({ id: 'og-url-exists', name: 'OG URL', category: 'og', severity: 'warning' }, 'warn', 'Missing og:url', { recommendation: 'Add og:url with the canonical URL of the page' });
+                return createResult({ id: 'og-url-exists', name: 'OG URL', category: 'og', severity: 'warning' }, 'warn', 'Missing og:url', {
+                    recommendation: 'Add og:url with the canonical URL of the page',
+                    evidence: {
+                        found: 'No og:url meta tag',
+                        expected: '<meta property="og:url" content="https://yoursite.com/page">',
+                        impact: 'Without og:url, social platforms may use incorrect URLs, causing share count fragmentation',
+                        example: '<meta property="og:url" content="https://yoursite.com/products/shoes">'
+                    }
+                });
             }
             return createResult({ id: 'og-url-exists', name: 'OG URL', category: 'og', severity: 'warning' }, 'pass', 'og:url is defined', { value: ctx.ogUrl });
         },
@@ -298,7 +406,15 @@ export const metaRules = [
         description: 'og:type should be defined (website, article, etc.)',
         check: (ctx) => {
             if (!ctx.ogType) {
-                return createResult({ id: 'og-type-exists', name: 'OG Type', category: 'og', severity: 'warning' }, 'warn', 'Missing og:type', { recommendation: 'Add og:type (website, article, product, etc.)' });
+                return createResult({ id: 'og-type-exists', name: 'OG Type', category: 'og', severity: 'warning' }, 'warn', 'Missing og:type', {
+                    recommendation: 'Add og:type (website, article, product, etc.)',
+                    evidence: {
+                        found: 'No og:type meta tag',
+                        expected: '<meta property="og:type" content="website"> or "article"',
+                        impact: 'Social platforms use og:type to determine how to display the content (website vs article vs product)',
+                        example: '<meta property="og:type" content="article"> for blog posts\n<meta property="og:type" content="website"> for general pages'
+                    }
+                });
             }
             return createResult({ id: 'og-type-exists', name: 'OG Type', category: 'og', severity: 'warning' }, 'pass', `og:type is defined (${ctx.ogType})`);
         },
@@ -310,13 +426,23 @@ export const metaRules = [
         severity: 'warning',
         description: 'og:image URL should be under 2000 characters',
         check: (ctx) => {
-            if (!ctx.ogImage)
-                return null;
+            if (!ctx.ogImage) {
+                return createResult({ id: 'og-image-url-length', name: 'OG Image URL Length', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:image)', { recommendation: 'This rule checks og:image URL length when present' });
+            }
             const maxLen = SEO_THRESHOLDS.og.meta.maxUrlLength;
             if (ctx.ogImage.length > maxLen) {
-                return createResult({ id: 'og-image-url-length', name: 'OG Image URL Length', category: 'og', severity: 'warning' }, 'warn', `og:image URL too long (${ctx.ogImage.length} chars, max: ${maxLen})`, { value: ctx.ogImage.length, recommendation: 'Shorten the image URL path' });
+                return createResult({ id: 'og-image-url-length', name: 'OG Image URL Length', category: 'og', severity: 'warning' }, 'warn', `og:image URL too long (${ctx.ogImage.length} chars, max: ${maxLen})`, {
+                    value: ctx.ogImage.length,
+                    recommendation: 'Shorten the image URL path',
+                    evidence: {
+                        found: `${ctx.ogImage.length} characters`,
+                        expected: `Less than ${maxLen} characters`,
+                        impact: 'Very long URLs may be truncated or rejected by some social platforms',
+                        example: 'Use shorter paths: "/og-images/product-123.jpg" instead of "/assets/generated/optimized/social-media/open-graph/product-images/..."'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'og-image-url-length', name: 'OG Image URL Length', category: 'og', severity: 'warning' }, 'info', 'Not applicable (og:image URL length is acceptable)', { recommendation: 'This rule checks if og:image URL exceeds length limits' });
         },
     },
     {
@@ -326,15 +452,24 @@ export const metaRules = [
         severity: 'warning',
         description: 'og:image URL should not have expiring tokens or excessive query params',
         check: (ctx) => {
-            if (!ctx.ogImage)
-                return null;
+            if (!ctx.ogImage) {
+                return createResult({ id: 'og-image-url-quality', name: 'OG Image URL Quality', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:image)', { recommendation: 'This rule checks og:image URL for expiring tokens when present' });
+            }
             try {
                 const url = new URL(ctx.ogImage);
                 const params = url.searchParams;
                 const expiringParams = ['expires', 'exp', 'token', 'sig', 'signature', 'auth'];
                 const hasExpiring = expiringParams.some((p) => params.has(p));
                 if (hasExpiring) {
-                    return createResult({ id: 'og-image-url-quality', name: 'OG Image URL Quality', category: 'og', severity: 'warning' }, 'warn', 'og:image URL may have expiring tokens (Meta caches images)', { recommendation: 'Use permanent URLs without expiration tokens for og:image' });
+                    return createResult({ id: 'og-image-url-quality', name: 'OG Image URL Quality', category: 'og', severity: 'warning' }, 'warn', 'og:image URL may have expiring tokens (Meta caches images)', {
+                        recommendation: 'Use permanent URLs without expiration tokens for og:image',
+                        evidence: {
+                            found: `URL contains expiring parameters: ${ctx.ogImage}`,
+                            expected: 'Permanent URL without time-based tokens',
+                            impact: 'Meta caches images for weeks. Expiring URLs will break after cache, showing broken images on shares',
+                            example: 'Instead of "...?token=abc&expires=123", use a permanent path like "/og-images/product.jpg"'
+                        }
+                    });
                 }
                 if (Array.from(params.keys()).length > 5) {
                     return createResult({ id: 'og-image-url-quality', name: 'OG Image URL Quality', category: 'og', severity: 'warning' }, 'info', 'og:image URL has many query parameters', { recommendation: 'Simplify og:image URL for better caching' });
@@ -342,7 +477,7 @@ export const metaRules = [
             }
             catch {
             }
-            return null;
+            return createResult({ id: 'og-image-url-quality', name: 'OG Image URL Quality', category: 'og', severity: 'warning' }, 'info', 'Not applicable (og:image URL has good quality)', { recommendation: 'This rule checks for expiring tokens and excessive query parameters' });
         },
     },
     {
@@ -352,15 +487,16 @@ export const metaRules = [
         severity: 'info',
         description: 'og:description should not have excessive emojis',
         check: (ctx) => {
-            if (!ctx.ogDescription)
-                return null;
+            if (!ctx.ogDescription) {
+                return createResult({ id: 'og-description-emojis', name: 'OG Description Emojis', category: 'og', severity: 'info' }, 'info', 'Not applicable (no og:description)', { recommendation: 'This rule checks emoji usage in og:description when present' });
+            }
             const emojiRegex = /[\u{1F300}-\u{1F9FF}]|[\u{2600}-\u{26FF}]|[\u{2700}-\u{27BF}]|[\u{1F600}-\u{1F64F}]|[\u{1F680}-\u{1F6FF}]/gu;
             const emojis = ctx.ogDescription.match(emojiRegex) || [];
             const maxEmojis = SEO_THRESHOLDS.og.meta.maxDescriptionEmojis;
             if (emojis.length > maxEmojis) {
                 return createResult({ id: 'og-description-emojis', name: 'OG Description Emojis', category: 'og', severity: 'info' }, 'info', `og:description has ${emojis.length} emojis (recommended max: ${maxEmojis})`, { value: emojis.length, recommendation: 'Reduce emojis in og:description for better compatibility' });
             }
-            return null;
+            return createResult({ id: 'og-description-emojis', name: 'OG Description Emojis', category: 'og', severity: 'info' }, 'info', 'Not applicable (og:description has acceptable emoji count)', { recommendation: 'This rule checks for excessive emoji usage in og:description' });
         },
     },
     {
@@ -370,18 +506,29 @@ export const metaRules = [
         severity: 'warning',
         description: 'og:title should not be mostly uppercase (Meta may flag as low quality)',
         check: (ctx) => {
-            if (!ctx.ogTitle)
-                return null;
+            if (!ctx.ogTitle) {
+                return createResult({ id: 'og-title-caps', name: 'OG Title Caps', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:title)', { recommendation: 'This rule checks capitalization in og:title when present' });
+            }
             const letters = ctx.ogTitle.replace(/[^a-zA-Z]/g, '');
-            if (letters.length < 5)
-                return null;
+            if (letters.length < 5) {
+                return createResult({ id: 'og-title-caps', name: 'OG Title Caps', category: 'og', severity: 'warning' }, 'info', 'Not applicable (og:title has too few letters to evaluate)', { recommendation: 'This rule checks for excessive uppercase in og:title' });
+            }
             const uppercase = letters.replace(/[^A-Z]/g, '').length;
             const percentage = Math.round((uppercase / letters.length) * 100);
             const maxCaps = SEO_THRESHOLDS.og.meta.maxCapsPercentage;
             if (percentage > maxCaps) {
-                return createResult({ id: 'og-title-caps', name: 'OG Title Caps', category: 'og', severity: 'warning' }, 'warn', `og:title has ${percentage}% uppercase (Meta may flag as low quality)`, { value: percentage, recommendation: 'Use normal capitalization in og:title' });
+                return createResult({ id: 'og-title-caps', name: 'OG Title Caps', category: 'og', severity: 'warning' }, 'warn', `og:title has ${percentage}% uppercase (Meta may flag as low quality)`, {
+                    value: percentage,
+                    recommendation: 'Use normal capitalization in og:title',
+                    evidence: {
+                        found: `${percentage}% uppercase letters in "${ctx.ogTitle}"`,
+                        expected: `Less than ${maxCaps}% uppercase`,
+                        impact: 'Meta may flag posts with excessive capitals as spam or low quality, reducing reach',
+                        example: 'Instead of "BUY NOW - HUGE SALE", use "Buy Now - Huge Sale on All Items"'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'og-title-caps', name: 'OG Title Caps', category: 'og', severity: 'warning' }, 'info', 'Not applicable (og:title uses proper capitalization)', { recommendation: 'This rule checks for excessive uppercase in og:title' });
         },
     },
     {
@@ -402,7 +549,15 @@ export const metaRules = [
                 .filter(([, value]) => !value)
                 .map(([key]) => key);
             if (missing.length > 0) {
-                return createResult({ id: 'og-meta-complete', name: 'Meta Complete', category: 'og', severity: 'warning' }, 'warn', `Missing required Meta tags: ${missing.join(', ')}`, { recommendation: 'Meta (Facebook/Instagram) requires all 5 OG tags for proper previews' });
+                return createResult({ id: 'og-meta-complete', name: 'Meta Complete', category: 'og', severity: 'warning' }, 'warn', `Missing required Meta tags: ${missing.join(', ')}`, {
+                    recommendation: 'Meta (Facebook/Instagram) requires all 5 OG tags for proper previews',
+                    evidence: {
+                        found: `Missing: ${missing.join(', ')}`,
+                        expected: 'All 5 tags: og:title, og:description, og:image, og:url, og:type',
+                        impact: 'Incomplete Open Graph data leads to poor or broken previews on Facebook, Instagram, and LinkedIn',
+                        example: 'Add all required tags:\n<meta property="og:title" content="...">\n<meta property="og:description" content="...">\n<meta property="og:image" content="...">\n<meta property="og:url" content="...">\n<meta property="og:type" content="website">'
+                    }
+                });
             }
             return createResult({ id: 'og-meta-complete', name: 'Meta Complete', category: 'og', severity: 'warning' }, 'pass', 'All required Meta OG tags present');
         },
@@ -417,7 +572,7 @@ export const metaRules = [
             if (ctx.ogTitle && !ctx.title) {
                 return createResult({ id: 'og-fallback-meta-title', name: 'Fallback Meta Title', category: 'og', severity: 'info' }, 'info', 'No <title> tag found (og:title exists)', { recommendation: 'Add <title> tag as fallback for universal compatibility' });
             }
-            return null;
+            return createResult({ id: 'og-fallback-meta-title', name: 'Fallback Meta Title', category: 'og', severity: 'info' }, 'info', 'Not applicable (page has title tag or no og:title)', { recommendation: 'This rule checks for title tag when og:title exists' });
         },
     },
     {
@@ -427,19 +582,28 @@ export const metaRules = [
         severity: 'warning',
         description: 'og:image should not have redirect chains (Meta blocks >2 redirects)',
         check: (ctx) => {
-            if (!ctx.ogImage)
-                return null;
+            if (!ctx.ogImage) {
+                return createResult({ id: 'og-image-redirects', name: 'OG Image Redirects', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:image)', { recommendation: 'This rule checks og:image URL for redirect patterns when present' });
+            }
             try {
                 const url = new URL(ctx.ogImage);
                 const redirectPatterns = ['redirect', 'proxy', 'forward', 'goto', 'redir', 'bounce'];
                 const hasRedirectPattern = redirectPatterns.some((p) => url.pathname.toLowerCase().includes(p) || url.hostname.toLowerCase().includes(p));
                 if (hasRedirectPattern) {
-                    return createResult({ id: 'og-image-redirects', name: 'OG Image Redirects', category: 'og', severity: 'warning' }, 'warn', 'og:image URL may contain redirects (Meta blocks >2 redirect chains)', { recommendation: 'Use direct, permanent image URLs for og:image' });
+                    return createResult({ id: 'og-image-redirects', name: 'OG Image Redirects', category: 'og', severity: 'warning' }, 'warn', 'og:image URL may contain redirects (Meta blocks >2 redirect chains)', {
+                        recommendation: 'Use direct, permanent image URLs for og:image',
+                        evidence: {
+                            found: `URL contains redirect pattern: ${ctx.ogImage}`,
+                            expected: 'Direct URL to the image file',
+                            impact: 'Facebook blocks images with more than 2 redirects, causing broken previews',
+                            example: 'Instead of "/redirect?url=image.jpg", use direct URL: "/images/og-image.jpg"'
+                        }
+                    });
                 }
             }
             catch {
             }
-            return null;
+            return createResult({ id: 'og-image-redirects', name: 'OG Image Redirects', category: 'og', severity: 'warning' }, 'info', 'Not applicable (og:image URL has no redirect patterns)', { recommendation: 'This rule checks for redirect patterns in og:image URL' });
         },
     },
     {
@@ -449,22 +613,39 @@ export const metaRules = [
         severity: 'warning',
         description: 'og:image must be publicly accessible (no auth, no private URLs)',
         check: (ctx) => {
-            if (!ctx.ogImage)
-                return null;
+            if (!ctx.ogImage) {
+                return createResult({ id: 'og-image-public', name: 'OG Image Public', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:image)', { recommendation: 'This rule checks og:image URL accessibility when present' });
+            }
             try {
                 const url = new URL(ctx.ogImage);
                 if (url.username || url.password) {
-                    return createResult({ id: 'og-image-public', name: 'OG Image Public', category: 'og', severity: 'warning' }, 'fail', 'og:image URL contains credentials (will fail on social platforms)', { recommendation: 'Use publicly accessible URLs without authentication' });
+                    return createResult({ id: 'og-image-public', name: 'OG Image Public', category: 'og', severity: 'warning' }, 'fail', 'og:image URL contains credentials (will fail on social platforms)', {
+                        recommendation: 'Use publicly accessible URLs without authentication',
+                        evidence: {
+                            found: 'URL contains username/password credentials',
+                            expected: 'Public URL without authentication',
+                            impact: 'Social platforms cannot fetch images with HTTP authentication, resulting in broken previews',
+                            example: 'Instead of "https://user:pass@site.com/image.jpg", host image publicly at "https://cdn.site.com/og-image.jpg"'
+                        }
+                    });
                 }
                 const hostname = url.hostname.toLowerCase();
                 const privatePatterns = ['localhost', '127.0.0.1', '192.168.', '10.', '172.16.', '172.17.', '172.18.', '172.19.'];
                 if (privatePatterns.some((p) => hostname.startsWith(p) || hostname === p.slice(0, -1))) {
-                    return createResult({ id: 'og-image-public', name: 'OG Image Public', category: 'og', severity: 'warning' }, 'fail', 'og:image URL points to localhost/private IP (not accessible)', { recommendation: 'Use publicly accessible URLs for og:image' });
+                    return createResult({ id: 'og-image-public', name: 'OG Image Public', category: 'og', severity: 'warning' }, 'fail', 'og:image URL points to localhost/private IP (not accessible)', {
+                        recommendation: 'Use publicly accessible URLs for og:image',
+                        evidence: {
+                            found: `Private/local URL: ${ctx.ogImage}`,
+                            expected: 'Public URL accessible from the internet',
+                            impact: 'Social platforms cannot access localhost or private IPs, resulting in broken image previews',
+                            example: 'Instead of "http://localhost:3000/image.jpg", deploy to "https://yoursite.com/og-image.jpg"'
+                        }
+                    });
                 }
             }
             catch {
             }
-            return null;
+            return createResult({ id: 'og-image-public', name: 'OG Image Public', category: 'og', severity: 'warning' }, 'info', 'Not applicable (og:image URL is publicly accessible)', { recommendation: 'This rule checks for authentication or private IPs in og:image URL' });
         },
     },
     {
@@ -475,11 +656,27 @@ export const metaRules = [
         description: 'twitter:card should be defined (summary or summary_large_image)',
         check: (ctx) => {
             if (!ctx.twitterCard) {
-                return createResult({ id: 'twitter-card-exists', name: 'Twitter Card', category: 'twitter', severity: 'warning' }, 'warn', 'Missing twitter:card', { recommendation: 'Add twitter:card (summary or summary_large_image)' });
+                return createResult({ id: 'twitter-card-exists', name: 'Twitter Card', category: 'twitter', severity: 'warning' }, 'warn', 'Missing twitter:card', {
+                    recommendation: 'Add twitter:card (summary or summary_large_image)',
+                    evidence: {
+                        found: 'No twitter:card meta tag',
+                        expected: '<meta name="twitter:card" content="summary_large_image">',
+                        impact: 'Twitter will use a default card type, which may not display optimally',
+                        example: '<meta name="twitter:card" content="summary_large_image">\n<meta name="twitter:card" content="summary"> for smaller images'
+                    }
+                });
             }
             const validCards = ['summary', 'summary_large_image', 'player', 'app'];
             if (!validCards.includes(ctx.twitterCard)) {
-                return createResult({ id: 'twitter-card-exists', name: 'Twitter Card', category: 'twitter', severity: 'warning' }, 'warn', `Invalid twitter:card value: ${ctx.twitterCard}`, { recommendation: 'Use summary or summary_large_image' });
+                return createResult({ id: 'twitter-card-exists', name: 'Twitter Card', category: 'twitter', severity: 'warning' }, 'warn', `Invalid twitter:card value: ${ctx.twitterCard}`, {
+                    recommendation: 'Use summary or summary_large_image',
+                    evidence: {
+                        found: `Invalid value: "${ctx.twitterCard}"`,
+                        expected: 'One of: summary, summary_large_image, player, app',
+                        impact: 'Invalid card types are ignored by Twitter, falling back to default display',
+                        example: '<meta name="twitter:card" content="summary_large_image">'
+                    }
+                });
             }
             return createResult({ id: 'twitter-card-exists', name: 'Twitter Card', category: 'twitter', severity: 'warning' }, 'pass', `twitter:card is defined (${ctx.twitterCard})`);
         },
@@ -492,14 +689,24 @@ export const metaRules = [
         description: 'twitter:title should be 55-70 characters',
         check: (ctx) => {
             const title = ctx.twitterTitle || ctx.ogTitle;
-            if (!title)
-                return null;
+            if (!title) {
+                return createResult({ id: 'twitter-title-length', name: 'Twitter Title Length', category: 'twitter', severity: 'warning' }, 'info', 'Not applicable (no twitter:title or og:title)', { recommendation: 'This rule checks Twitter title length when present' });
+            }
             const len = title.length;
             const { ideal, max } = SEO_THRESHOLDS.twitter.title;
             if (len > max) {
-                return createResult({ id: 'twitter-title-length', name: 'Twitter Title Length', category: 'twitter', severity: 'warning' }, 'warn', `twitter:title too long (${len} chars, max: ${max})`, { value: len, recommendation: `Shorten to ${ideal.max} characters` });
+                return createResult({ id: 'twitter-title-length', name: 'Twitter Title Length', category: 'twitter', severity: 'warning' }, 'warn', `twitter:title too long (${len} chars, max: ${max})`, {
+                    value: len,
+                    recommendation: `Shorten to ${ideal.max} characters`,
+                    evidence: {
+                        found: `${len} characters`,
+                        expected: `${ideal.min}-${ideal.max} characters (max ${max})`,
+                        impact: 'Twitter truncates long titles, potentially hiding key information in card previews',
+                        example: 'Keep it concise: "New Product Launch - 50% Off" (34 chars)'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'twitter-title-length', name: 'Twitter Title Length', category: 'twitter', severity: 'warning' }, 'info', 'Not applicable (Twitter title length is acceptable)', { recommendation: 'This rule checks if Twitter title exceeds length limits' });
         },
     },
     {
@@ -510,14 +717,24 @@ export const metaRules = [
         description: 'twitter:description should be 125-200 characters',
         check: (ctx) => {
             const description = ctx.twitterDescription || ctx.ogDescription;
-            if (!description)
-                return null;
+            if (!description) {
+                return createResult({ id: 'twitter-description-length', name: 'Twitter Description Length', category: 'twitter', severity: 'warning' }, 'info', 'Not applicable (no twitter:description or og:description)', { recommendation: 'This rule checks Twitter description length when present' });
+            }
             const len = description.length;
             const { max } = SEO_THRESHOLDS.twitter.description;
             if (len > max) {
-                return createResult({ id: 'twitter-description-length', name: 'Twitter Description Length', category: 'twitter', severity: 'warning' }, 'warn', `twitter:description too long (${len} chars, max: ${max})`, { value: len, recommendation: `Shorten to ${max} characters` });
+                return createResult({ id: 'twitter-description-length', name: 'Twitter Description Length', category: 'twitter', severity: 'warning' }, 'warn', `twitter:description too long (${len} chars, max: ${max})`, {
+                    value: len,
+                    recommendation: `Shorten to ${max} characters`,
+                    evidence: {
+                        found: `${len} characters`,
+                        expected: `125-${max} characters`,
+                        impact: 'Twitter truncates descriptions over 200 characters, potentially hiding your call-to-action',
+                        example: 'Concise description: "Discover the best deals on electronics. Free shipping & 30-day returns." (89 chars)'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'twitter-description-length', name: 'Twitter Description Length', category: 'twitter', severity: 'warning' }, 'info', 'Not applicable (Twitter description length is acceptable)', { recommendation: 'This rule checks if Twitter description exceeds length limits' });
         },
     },
     {
@@ -527,8 +744,9 @@ export const metaRules = [
         severity: 'warning',
         description: 'Title should have at least 10 characters for SEO value',
         check: (ctx) => {
-            if (!ctx.title)
-                return null;
+            if (!ctx.title) {
+                return createResult({ id: 'title-too-short', name: 'Title Too Short', category: 'title', severity: 'warning' }, 'info', 'Not applicable (no title tag)', { recommendation: 'This rule checks if title is too short when present' });
+            }
             const len = ctx.titleLength ?? ctx.title.length;
             if (len <= 10) {
                 return createResult({ id: 'title-too-short', name: 'Title Too Short', category: 'title', severity: 'warning' }, 'warn', `Title is very short (${len} chars)`, {
@@ -541,7 +759,47 @@ export const metaRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'title-too-short', name: 'Title Too Short', category: 'title', severity: 'warning' }, 'info', 'Not applicable (title has sufficient length)', { recommendation: 'This rule checks if title is shorter than 10 characters' });
+        },
+    },
+    {
+        id: 'keywords-in-title',
+        name: 'Keywords in Title',
+        category: 'title',
+        severity: 'warning',
+        description: 'Title should contain main keywords found in content',
+        check: (ctx) => {
+            if (ctx.keywordsInTitle === false && ctx.topKeywords && ctx.topKeywords.length > 0) {
+                return createResult({ id: 'keywords-in-title', name: 'Keywords in Title', category: 'title', severity: 'warning' }, 'warn', 'Title does not appear to contain top keywords', {
+                    recommendation: 'Include your main target keywords in the page title.',
+                    evidence: {
+                        found: `Title: "${ctx.title}"`,
+                        expected: `Should contain one of: ${ctx.topKeywords.join(', ')}`,
+                        impact: 'Keywords in title are a strong ranking signal.'
+                    }
+                });
+            }
+            return createResult({ id: 'keywords-in-title', name: 'Keywords in Title', category: 'title', severity: 'warning' }, 'info', 'Not applicable (title contains keywords or no keyword data)', { recommendation: 'This rule checks if title contains main keywords from content' });
+        },
+    },
+    {
+        id: 'keywords-in-description',
+        name: 'Keywords in Description',
+        category: 'meta',
+        severity: 'info',
+        description: 'Meta description should contain main keywords',
+        check: (ctx) => {
+            if (ctx.keywordsInDescription === false && ctx.topKeywords && ctx.topKeywords.length > 0) {
+                return createResult({ id: 'keywords-in-description', name: 'Keywords in Description', category: 'meta', severity: 'info' }, 'info', 'Meta description does not appear to contain top keywords', {
+                    recommendation: 'Include main keywords in the description to embolden them in search results.',
+                    evidence: {
+                        found: 'Description does not match top keywords',
+                        expected: `Should contain one of: ${ctx.topKeywords.join(', ')}`,
+                        impact: 'Keywords in description are bolded in SERPs, improving CTR.'
+                    }
+                });
+            }
+            return createResult({ id: 'keywords-in-description', name: 'Keywords in Description', category: 'meta', severity: 'info' }, 'info', 'Not applicable (description contains keywords or no keyword data)', { recommendation: 'This rule checks if meta description contains main keywords' });
         },
     },
 ];