recker 1.0.42 → 1.0.43-next.7a08602

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,15 @@ 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 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 +124,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 +134,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,8 +174,9 @@ 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) {
@@ -139,7 +184,7 @@ export const metaRules = [
                     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 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 +205,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,8 +215,9 @@ 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) {
@@ -190,13 +236,14 @@ 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 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 +264,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,8 +274,9 @@ 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) {
@@ -259,7 +307,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,8 +317,9 @@ 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' });
             }
@@ -310,13 +359,14 @@ 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 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,8 +376,9 @@ 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;
@@ -342,7 +393,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 +403,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 +422,20 @@ 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 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' });
         },
     },
     {
@@ -417,7 +471,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,8 +481,9 @@ 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'];
@@ -439,7 +494,7 @@ export const metaRules = [
             }
             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,8 +504,9 @@ 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) {
@@ -464,7 +520,7 @@ export const metaRules = [
             }
             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' });
         },
     },
     {
@@ -492,14 +548,15 @@ 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 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 +567,15 @@ 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 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 +585,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 +600,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' });
         },
     },
 ];

package/dist/seo/rules/mobile.js

@@ -26,8 +26,9 @@ export const mobileRules = [
         severity: 'warning',
         description: 'Viewport should allow user scaling for accessibility',
         check: (ctx) => {
-            if (!ctx.viewportContent)
-                return null;
+            if (!ctx.viewportContent) {
+                return createResult({ id: 'viewport-scalable', name: 'Viewport Scalable', category: 'mobile', severity: 'warning' }, 'info', 'Not applicable (no viewport meta tag)', { recommendation: 'First add a viewport meta tag, then ensure it allows user scaling' });
+            }
             const content = ctx.viewportContent.toLowerCase();
             const hasUserScalableNo = /user-scalable\s*=\s*no/.test(content);
             const hasMaximumScale1 = /maximum-scale\s*=\s*1(\.0)?/.test(content);
@@ -48,4 +49,113 @@ export const mobileRules = [
             return createResult({ id: 'viewport-scalable', name: 'Viewport Scalable', category: 'mobile', severity: 'warning' }, 'pass', 'Viewport allows user scaling');
         },
     },
+    {
+        id: 'viewport-device-width',
+        name: 'Viewport Device Width',
+        category: 'mobile',
+        severity: 'warning',
+        description: 'Viewport should use width=device-width for responsive design',
+        check: (ctx) => {
+            if (!ctx.viewportContent) {
+                return createResult({ id: 'viewport-device-width', name: 'Viewport Device Width', category: 'mobile', severity: 'warning' }, 'info', 'Not applicable (no viewport meta tag)', { recommendation: 'First add a viewport meta tag with width=device-width' });
+            }
+            const content = ctx.viewportContent.toLowerCase();
+            const hasDeviceWidth = /width\s*=\s*device-width/.test(content);
+            const hasFixedWidth = /width\s*=\s*(\d+)/.test(content);
+            if (hasFixedWidth && !hasDeviceWidth) {
+                const match = content.match(/width\s*=\s*(\d+)/);
+                const fixedWidth = match ? match[1] : 'unknown';
+                return createResult({ id: 'viewport-device-width', name: 'Viewport Device Width', category: 'mobile', severity: 'warning' }, 'warn', `Viewport uses fixed width (${fixedWidth}px) instead of device-width`, {
+                    recommendation: 'Use width=device-width to make your site responsive across all devices',
+                    evidence: {
+                        found: ctx.viewportContent,
+                        expected: 'width=device-width',
+                        impact: 'Fixed width viewports force users to scroll horizontally on different screen sizes',
+                        example: '<meta name="viewport" content="width=device-width, initial-scale=1">',
+                    },
+                });
+            }
+            if (!hasDeviceWidth) {
+                return createResult({ id: 'viewport-device-width', name: 'Viewport Device Width', category: 'mobile', severity: 'warning' }, 'info', 'Viewport missing width=device-width', {
+                    recommendation: 'Add width=device-width to ensure proper responsive behavior',
+                    evidence: {
+                        found: ctx.viewportContent,
+                        expected: 'width=device-width',
+                    },
+                });
+            }
+            return createResult({ id: 'viewport-device-width', name: 'Viewport Device Width', category: 'mobile', severity: 'warning' }, 'pass', 'Viewport uses device-width correctly');
+        },
+    },
+    {
+        id: 'viewport-initial-scale',
+        name: 'Viewport Initial Scale',
+        category: 'mobile',
+        severity: 'info',
+        description: 'Viewport should include initial-scale=1 for consistent initial zoom',
+        check: (ctx) => {
+            if (!ctx.viewportContent) {
+                return createResult({ id: 'viewport-initial-scale', name: 'Viewport Initial Scale', category: 'mobile', severity: 'info' }, 'info', 'Not applicable (no viewport meta tag)', { recommendation: 'First add a viewport meta tag with initial-scale=1' });
+            }
+            const content = ctx.viewportContent.toLowerCase();
+            const hasInitialScale = /initial-scale\s*=\s*1(\.0)?/.test(content);
+            if (!hasInitialScale) {
+                return createResult({ id: 'viewport-initial-scale', name: 'Viewport Initial Scale', category: 'mobile', severity: 'info' }, 'info', 'Viewport missing initial-scale=1', {
+                    recommendation: 'Add initial-scale=1 to set consistent initial zoom level',
+                    evidence: {
+                        found: ctx.viewportContent,
+                        expected: 'initial-scale=1',
+                        example: '<meta name="viewport" content="width=device-width, initial-scale=1">',
+                    },
+                });
+            }
+            return createResult({ id: 'viewport-initial-scale', name: 'Viewport Initial Scale', category: 'mobile', severity: 'info' }, 'pass', 'Viewport has initial-scale=1');
+        },
+    },
+    {
+        id: 'viewport-complete',
+        name: 'Viewport Complete Configuration',
+        category: 'mobile',
+        severity: 'info',
+        description: 'Viewport should have the complete recommended configuration',
+        check: (ctx) => {
+            if (!ctx.viewportContent) {
+                return createResult({ id: 'viewport-complete', name: 'Viewport Complete', category: 'mobile', severity: 'info' }, 'info', 'Not applicable (no viewport meta tag)', { recommendation: 'Add a complete viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1">' });
+            }
+            const content = ctx.viewportContent.toLowerCase();
+            const hasDeviceWidth = /width\s*=\s*device-width/.test(content);
+            const hasInitialScale = /initial-scale\s*=\s*1(\.0)?/.test(content);
+            const hasUserScalableNo = /user-scalable\s*=\s*no/.test(content);
+            const hasFixedWidth = /width\s*=\s*\d+/.test(content) && !hasDeviceWidth;
+            const issues = [];
+            if (!hasDeviceWidth)
+                issues.push('missing width=device-width');
+            if (!hasInitialScale)
+                issues.push('missing initial-scale=1');
+            if (hasUserScalableNo)
+                issues.push('has user-scalable=no');
+            if (hasFixedWidth)
+                issues.push('uses fixed width');
+            if (issues.length === 0) {
+                return createResult({ id: 'viewport-complete', name: 'Viewport Complete', category: 'mobile', severity: 'info' }, 'pass', 'Viewport has optimal configuration for mobile', { evidence: { found: ctx.viewportContent } });
+            }
+            if (issues.length >= 2 || hasFixedWidth) {
+                return createResult({ id: 'viewport-complete', name: 'Viewport Complete', category: 'mobile', severity: 'info' }, 'warn', `Viewport configuration has issues: ${issues.join(', ')}`, {
+                    recommendation: 'Use the recommended viewport configuration for best mobile experience',
+                    evidence: {
+                        found: ctx.viewportContent,
+                        expected: '<meta name="viewport" content="width=device-width, initial-scale=1">',
+                        issue: issues.join('; '),
+                    },
+                });
+            }
+            return createResult({ id: 'viewport-complete', name: 'Viewport Complete', category: 'mobile', severity: 'info' }, 'info', `Viewport configuration could be improved: ${issues.join(', ')}`, {
+                recommendation: 'Consider using the complete recommended viewport configuration',
+                evidence: {
+                    found: ctx.viewportContent,
+                    expected: '<meta name="viewport" content="width=device-width, initial-scale=1">',
+                },
+            });
+        },
+    },
 ];