recker 1.0.43 → 1.0.44

package/dist/seo/rules/social.js

@@ -7,10 +7,12 @@ export const socialRules = [
         severity: 'warning',
         description: 'Open Graph images should meet minimum size requirements',
         check: (ctx) => {
-            if (!ctx.ogImage)
-                return null;
-            if (!ctx.ogImageDimensions)
-                return null;
+            if (!ctx.ogImage) {
+                return createResult({ id: 'social-og-image-size', name: 'OG Image Size', category: 'og', severity: 'warning' }, 'info', 'Not applicable (no og:image)', { recommendation: 'This rule checks og:image dimensions when present' });
+            }
+            if (!ctx.ogImageDimensions) {
+                return createResult({ id: 'social-og-image-size', name: 'OG Image Size', category: 'og', severity: 'warning' }, 'info', 'Not applicable (og:image dimensions not available)', { recommendation: 'This rule checks if og:image meets minimum size requirements' });
+            }
             const { width, height } = ctx.ogImageDimensions;
             const minWidth = 1200;
             const minHeight = 630;
@@ -35,8 +37,9 @@ export const socialRules = [
         severity: 'info',
         description: 'Open Graph images should use optimal aspect ratio',
         check: (ctx) => {
-            if (!ctx.ogImageDimensions)
-                return null;
+            if (!ctx.ogImageDimensions) {
+                return createResult({ id: 'social-og-image-aspect-ratio', name: 'OG Image Aspect Ratio', category: 'og', severity: 'info' }, 'info', 'Not applicable (og:image dimensions not available)', { recommendation: 'This rule checks og:image aspect ratio when dimensions are available' });
+            }
             const { width, height } = ctx.ogImageDimensions;
             const ratio = width / height;
             const optimalRatio = 1.91;
@@ -61,8 +64,9 @@ export const socialRules = [
         severity: 'info',
         description: 'Open Graph should specify content locale',
         check: (ctx) => {
-            if (ctx.ogLocale === undefined)
-                return null;
+            if (ctx.ogLocale === undefined) {
+                return createResult({ id: 'social-og-locale', name: 'OG Locale', category: 'og', severity: 'info' }, 'info', 'Not applicable (og:locale property not checked)', { recommendation: 'This rule checks og:locale when locale data is available' });
+            }
             if (!ctx.ogLocale) {
                 return createResult({ id: 'social-og-locale', name: 'OG Locale', category: 'og', severity: 'info' }, 'info', 'Missing og:locale', {
                     recommendation: 'Add og:locale for international content',
@@ -82,12 +86,15 @@ export const socialRules = [
         severity: 'info',
         description: 'Multi-language sites should specify alternate locales',
         check: (ctx) => {
-            if (!ctx.ogLocale)
-                return null;
-            if (!ctx.hreflangTags || ctx.hreflangTags.length <= 1)
-                return null;
-            if (ctx.ogLocaleAlternate === undefined)
-                return null;
+            if (!ctx.ogLocale) {
+                return createResult({ id: 'social-og-locale-alternate', name: 'OG Locale Alternates', category: 'og', severity: 'info' }, 'info', 'Not applicable (no og:locale)', { recommendation: 'This rule checks for alternate locales when og:locale is present' });
+            }
+            if (!ctx.hreflangTags || ctx.hreflangTags.length <= 1) {
+                return createResult({ id: 'social-og-locale-alternate', name: 'OG Locale Alternates', category: 'og', severity: 'info' }, 'info', 'Not applicable (single language site)', { recommendation: 'This rule checks for og:locale:alternate on multi-language sites' });
+            }
+            if (ctx.ogLocaleAlternate === undefined) {
+                return createResult({ id: 'social-og-locale-alternate', name: 'OG Locale Alternates', category: 'og', severity: 'info' }, 'info', 'Not applicable (og:locale:alternate property not checked)', { recommendation: 'This rule checks og:locale:alternate when data is available' });
+            }
             if (!ctx.ogLocaleAlternate || ctx.ogLocaleAlternate.length === 0) {
                 return createResult({ id: 'social-og-locale-alternate', name: 'OG Locale Alternates', category: 'og', severity: 'info' }, 'info', 'Missing og:locale:alternate for multi-language site', {
                     recommendation: 'Add og:locale:alternate for other language versions',
@@ -108,10 +115,12 @@ export const socialRules = [
         severity: 'info',
         description: 'Article pages should include article-specific Open Graph tags',
         check: (ctx) => {
-            if (ctx.ogType !== 'article')
-                return null;
-            if (ctx.ogArticleTags === undefined)
-                return null;
+            if (ctx.ogType !== 'article') {
+                return createResult({ id: 'social-og-article-tags', name: 'OG Article Tags', category: 'og', severity: 'info' }, 'info', 'Not applicable (page is not an article)', { recommendation: 'This rule checks article-specific Open Graph tags for article pages' });
+            }
+            if (ctx.ogArticleTags === undefined) {
+                return createResult({ id: 'social-og-article-tags', name: 'OG Article Tags', category: 'og', severity: 'info' }, 'info', 'Not applicable (article tags property not checked)', { recommendation: 'This rule checks article-specific Open Graph tags when data is available' });
+            }
             const missing = [];
             if (!ctx.ogArticlePublishedTime)
                 missing.push('article:published_time');
@@ -137,8 +146,9 @@ export const socialRules = [
         severity: 'info',
         description: 'Consider using summary_large_image for better visibility',
         check: (ctx) => {
-            if (!ctx.twitterCard)
-                return null;
+            if (!ctx.twitterCard) {
+                return createResult({ id: 'social-twitter-large-image', name: 'Twitter Large Image', category: 'twitter', severity: 'info' }, 'info', 'Not applicable (no twitter:card)', { recommendation: 'This rule checks Twitter card type when present' });
+            }
             if (ctx.twitterCard === 'summary') {
                 return createResult({ id: 'social-twitter-large-image', name: 'Twitter Large Image', category: 'twitter', severity: 'info' }, 'info', 'Using summary card (small image)', {
                     recommendation: 'Consider summary_large_image for more visual impact',
@@ -159,12 +169,15 @@ export const socialRules = [
         severity: 'info',
         description: 'Article pages should include twitter:creator for attribution',
         check: (ctx) => {
-            if (!ctx.twitterCard)
-                return null;
-            if (ctx.ogType !== 'article')
-                return null;
-            if (ctx.twitterCreator === undefined)
-                return null;
+            if (!ctx.twitterCard) {
+                return createResult({ id: 'social-twitter-creator', name: 'Twitter Creator', category: 'twitter', severity: 'info' }, 'info', 'Not applicable (no twitter:card)', { recommendation: 'This rule checks twitter:creator when Twitter Card is present' });
+            }
+            if (ctx.ogType !== 'article') {
+                return createResult({ id: 'social-twitter-creator', name: 'Twitter Creator', category: 'twitter', severity: 'info' }, 'info', 'Not applicable (page is not an article)', { recommendation: 'This rule checks twitter:creator for article pages' });
+            }
+            if (ctx.twitterCreator === undefined) {
+                return createResult({ id: 'social-twitter-creator', name: 'Twitter Creator', category: 'twitter', severity: 'info' }, 'info', 'Not applicable (twitter:creator property not checked)', { recommendation: 'This rule checks twitter:creator when data is available' });
+            }
             if (!ctx.twitterCreator) {
                 return createResult({ id: 'social-twitter-creator', name: 'Twitter Creator', category: 'twitter', severity: 'info' }, 'info', 'Missing twitter:creator on article', {
                     recommendation: 'Add twitter:creator for author attribution',
@@ -184,10 +197,12 @@ export const socialRules = [
         severity: 'info',
         description: 'Twitter images should have alt text for accessibility',
         check: (ctx) => {
-            if (!ctx.twitterImage)
-                return null;
-            if (ctx.twitterImageAlt === undefined)
-                return null;
+            if (!ctx.twitterImage) {
+                return createResult({ id: 'social-twitter-image-alt', name: 'Twitter Image Alt', category: 'twitter', severity: 'info' }, 'info', 'Not applicable (no twitter:image)', { recommendation: 'This rule checks twitter:image:alt when Twitter image is present' });
+            }
+            if (ctx.twitterImageAlt === undefined) {
+                return createResult({ id: 'social-twitter-image-alt', name: 'Twitter Image Alt', category: 'twitter', severity: 'info' }, 'info', 'Not applicable (twitter:image:alt property not checked)', { recommendation: 'This rule checks twitter:image:alt when data is available' });
+            }
             if (!ctx.twitterImageAlt) {
                 return createResult({ id: 'social-twitter-image-alt', name: 'Twitter Image Alt', category: 'twitter', severity: 'info' }, 'info', 'Missing twitter:image:alt', {
                     recommendation: 'Add alt text for Twitter card image',
@@ -207,10 +222,12 @@ export const socialRules = [
         severity: 'info',
         description: 'Professional content should include author information',
         check: (ctx) => {
-            if (ctx.ogType !== 'article')
-                return null;
-            if (ctx.linkedinAuthor === undefined && ctx.ogArticleAuthor === undefined)
-                return null;
+            if (ctx.ogType !== 'article') {
+                return createResult({ id: 'social-linkedin-author', name: 'LinkedIn Author', category: 'og', severity: 'info' }, 'info', 'Not applicable (page is not an article)', { recommendation: 'This rule checks author information for article pages' });
+            }
+            if (ctx.linkedinAuthor === undefined && ctx.ogArticleAuthor === undefined) {
+                return createResult({ id: 'social-linkedin-author', name: 'LinkedIn Author', category: 'og', severity: 'info' }, 'info', 'Not applicable (author properties not checked)', { recommendation: 'This rule checks author information when data is available' });
+            }
             if (!ctx.linkedinAuthor && !ctx.ogArticleAuthor) {
                 return createResult({ id: 'social-linkedin-author', name: 'LinkedIn Author', category: 'og', severity: 'info' }, 'info', 'No author specified for LinkedIn', {
                     recommendation: 'Add author for professional network sharing',
@@ -230,10 +247,12 @@ export const socialRules = [
         severity: 'info',
         description: 'E-commerce and recipe sites should support Pinterest Rich Pins',
         check: (ctx) => {
-            if (!ctx.isProductPage && ctx.ogType !== 'recipe')
-                return null;
-            if (ctx.pinterestRichPinSupport === undefined)
-                return null;
+            if (!ctx.isProductPage && ctx.ogType !== 'recipe') {
+                return createResult({ id: 'social-pinterest-rich-pins', name: 'Pinterest Rich Pins', category: 'og', severity: 'info' }, 'info', 'Not applicable (page is not a product or recipe)', { recommendation: 'This rule checks Pinterest Rich Pin support for e-commerce and recipe sites' });
+            }
+            if (ctx.pinterestRichPinSupport === undefined) {
+                return createResult({ id: 'social-pinterest-rich-pins', name: 'Pinterest Rich Pins', category: 'og', severity: 'info' }, 'info', 'Not applicable (Pinterest Rich Pin support not checked)', { recommendation: 'This rule checks for structured data when data is available' });
+            }
             if (!ctx.pinterestRichPinSupport) {
                 return createResult({ id: 'social-pinterest-rich-pins', name: 'Pinterest Rich Pins', category: 'og', severity: 'info' }, 'info', 'No Pinterest Rich Pin support detected', {
                     recommendation: 'Add structured data for Pinterest Rich Pins',
@@ -254,8 +273,9 @@ export const socialRules = [
         severity: 'info',
         description: 'Check for intentional Pinterest blocking',
         check: (ctx) => {
-            if (ctx.hasPinterestNopin === undefined)
-                return null;
+            if (ctx.hasPinterestNopin === undefined) {
+                return createResult({ id: 'social-pinterest-nopin', name: 'Pinterest Nopin', category: 'og', severity: 'info' }, 'info', 'Not applicable (Pinterest nopin property not checked)', { recommendation: 'This rule checks for Pinterest blocking when data is available' });
+            }
             if (ctx.hasPinterestNopin) {
                 return createResult({ id: 'social-pinterest-nopin', name: 'Pinterest Nopin', category: 'og', severity: 'info' }, 'info', 'Pinterest pinning is disabled', {
                     evidence: {
@@ -264,7 +284,7 @@ export const socialRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'social-pinterest-nopin', name: 'Pinterest Nopin', category: 'og', severity: 'info' }, 'info', 'Not applicable (Pinterest pinning is allowed)', { recommendation: 'This rule checks for intentional Pinterest blocking' });
         },
     },
     {
@@ -300,8 +320,9 @@ export const socialRules = [
         severity: 'info',
         description: 'Open Graph titles should be optimized for social platforms',
         check: (ctx) => {
-            if (!ctx.ogTitle)
-                return null;
+            if (!ctx.ogTitle) {
+                return createResult({ id: 'social-og-title-length', name: 'OG Title Length', category: 'og', severity: 'info' }, 'info', 'Not applicable (no og:title)', { recommendation: 'This rule checks og:title length for social platforms when present' });
+            }
             const length = ctx.ogTitle.length;
             const maxLength = 60;
             if (length > maxLength) {
@@ -324,8 +345,9 @@ export const socialRules = [
         severity: 'info',
         description: 'Open Graph descriptions should be optimized for social platforms',
         check: (ctx) => {
-            if (!ctx.ogDescription)
-                return null;
+            if (!ctx.ogDescription) {
+                return createResult({ id: 'social-og-description-length', name: 'OG Description Length', category: 'og', severity: 'info' }, 'info', 'Not applicable (no og:description)', { recommendation: 'This rule checks og:description length for social platforms when present' });
+            }
             const length = ctx.ogDescription.length;
             const minLength = 55;
             const maxLength = 200;
@@ -356,8 +378,9 @@ export const socialRules = [
         severity: 'info',
         description: 'Facebook App ID enables Insights and domain verification',
         check: (ctx) => {
-            if (ctx.fbAppId === undefined)
-                return null;
+            if (ctx.fbAppId === undefined) {
+                return createResult({ id: 'social-fb-app-id', name: 'Facebook App ID', category: 'og', severity: 'info' }, 'info', 'Not applicable (Facebook App ID property not checked)', { recommendation: 'This rule checks for fb:app_id when data is available' });
+            }
             if (!ctx.fbAppId) {
                 return createResult({ id: 'social-fb-app-id', name: 'Facebook App ID', category: 'og', severity: 'info' }, 'info', 'No Facebook App ID', {
                     recommendation: 'Add fb:app_id for Facebook Insights',
@@ -370,4 +393,211 @@ export const socialRules = [
             return createResult({ id: 'social-fb-app-id', name: 'Facebook App ID', category: 'og', severity: 'info' }, 'pass', 'Facebook App ID present');
         },
     },
+    {
+        id: 'social-links-presence',
+        name: 'Social Media Links',
+        category: 'og',
+        severity: 'info',
+        description: 'Site should link to social media profiles',
+        check: (ctx) => {
+            if (ctx.socialLinksFound && ctx.socialLinksFound.length > 0) {
+                return createResult({ id: 'social-links-presence', name: 'Social Media Links', category: 'og', severity: 'info' }, 'pass', `Found ${ctx.socialLinksFound.length} social media profile link(s)`, { value: ctx.socialLinksFound.length, evidence: { found: ctx.socialLinksFound.slice(0, 5) } });
+            }
+            return createResult({ id: 'social-links-presence', name: 'Social Media Links', category: 'og', severity: 'info' }, 'info', 'No social media profile links found', { recommendation: 'Link to your Facebook, Twitter, Instagram, etc. profiles to build trust.' });
+        },
+    },
+    {
+        id: 'social-links-accessibility',
+        name: 'Social Links Accessibility',
+        category: 'accessibility',
+        severity: 'warning',
+        description: 'Social media links should have accessible labels for screen readers',
+        check: (ctx) => {
+            if (!ctx.totalSocialLinks || ctx.totalSocialLinks === 0) {
+                return createResult({ id: 'social-links-accessibility', name: 'Social Links Accessibility', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no social links found)', { recommendation: 'This rule checks accessibility of social media links when present' });
+            }
+            if (ctx.socialLinksWithoutAccessibility === undefined) {
+                return createResult({ id: 'social-links-accessibility', name: 'Social Links Accessibility', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (social link accessibility not checked)', { recommendation: 'This rule checks for accessible labels on social links when data is available' });
+            }
+            if (ctx.socialLinksWithoutAccessibility > 0) {
+                const inaccessibleLinks = ctx.socialLinkDetails
+                    ?.filter(l => !l.hasAccessibility)
+                    .map(l => l.platform)
+                    .slice(0, 5);
+                return createResult({ id: 'social-links-accessibility', name: 'Social Links Accessibility', category: 'accessibility', severity: 'warning' }, 'warn', `${ctx.socialLinksWithoutAccessibility} social link(s) missing accessible labels`, {
+                    recommendation: 'Add aria-label, title, or visible text to social media links',
+                    evidence: {
+                        found: ctx.socialLinksWithoutAccessibility,
+                        expected: 'All social links should have accessible labels',
+                        impact: 'Screen reader users cannot identify the purpose of icon-only social links',
+                        example: '<a href="https://twitter.com/..." aria-label="Follow us on Twitter">',
+                        issue: inaccessibleLinks?.length ? `Inaccessible: ${inaccessibleLinks.join(', ')}` : undefined,
+                    },
+                });
+            }
+            return createResult({ id: 'social-links-accessibility', name: 'Social Links Accessibility', category: 'accessibility', severity: 'warning' }, 'pass', 'All social links have accessible labels');
+        },
+    },
+    {
+        id: 'social-links-security',
+        name: 'Social Links Security',
+        category: 'security',
+        severity: 'warning',
+        description: 'External social links should use rel="noopener" to prevent security vulnerabilities',
+        check: (ctx) => {
+            if (!ctx.totalSocialLinks || ctx.totalSocialLinks === 0) {
+                return createResult({ id: 'social-links-security', name: 'Social Links Security', category: 'security', severity: 'warning' }, 'info', 'Not applicable (no social links found)', { recommendation: 'This rule checks security attributes of social media links when present' });
+            }
+            if (ctx.socialLinksWithoutNoopener === undefined) {
+                return createResult({ id: 'social-links-security', name: 'Social Links Security', category: 'security', severity: 'warning' }, 'info', 'Not applicable (social link security not checked)', { recommendation: 'This rule checks for rel="noopener" on social links when data is available' });
+            }
+            const linksWithNewTab = ctx.socialLinkDetails?.filter(l => l.hasNewTab) || [];
+            if (linksWithNewTab.length === 0) {
+                return createResult({ id: 'social-links-security', name: 'Social Links Security', category: 'security', severity: 'warning' }, 'info', 'Not applicable (no social links with target="_blank")', { recommendation: 'This rule checks security for social links that open in new tabs' });
+            }
+            const insecureLinks = linksWithNewTab.filter(l => !l.hasNoopener);
+            if (insecureLinks.length > 0) {
+                return createResult({ id: 'social-links-security', name: 'Social Links Security', category: 'security', severity: 'warning' }, 'warn', `${insecureLinks.length} social link(s) with target="_blank" missing rel="noopener"`, {
+                    recommendation: 'Add rel="noopener noreferrer" to external links with target="_blank"',
+                    evidence: {
+                        found: insecureLinks.length,
+                        expected: 'All target="_blank" links should have rel="noopener"',
+                        impact: 'Without noopener, the opened page can access window.opener and potentially redirect your page (tabnabbing attack)',
+                        example: '<a href="https://twitter.com/..." target="_blank" rel="noopener noreferrer">',
+                        issue: insecureLinks.slice(0, 3).map(l => l.platform).join(', '),
+                    },
+                });
+            }
+            return createResult({ id: 'social-links-security', name: 'Social Links Security', category: 'security', severity: 'warning' }, 'pass', 'All social links opening in new tabs have proper security attributes');
+        },
+    },
+    {
+        id: 'social-links-new-tab',
+        name: 'Social Links New Tab',
+        category: 'og',
+        severity: 'info',
+        description: 'Social media links should open in a new tab to keep users on your site',
+        check: (ctx) => {
+            if (!ctx.totalSocialLinks || ctx.totalSocialLinks === 0) {
+                return createResult({ id: 'social-links-new-tab', name: 'Social Links New Tab', category: 'og', severity: 'info' }, 'info', 'Not applicable (no social links found)', { recommendation: 'This rule checks if social links open in new tabs when present' });
+            }
+            if (ctx.socialLinksWithoutNewTab === undefined) {
+                return createResult({ id: 'social-links-new-tab', name: 'Social Links New Tab', category: 'og', severity: 'info' }, 'info', 'Not applicable (social link new tab property not checked)', { recommendation: 'This rule checks target="_blank" on social links when data is available' });
+            }
+            if (ctx.socialLinksWithoutNewTab > 0) {
+                const linksWithoutNewTab = ctx.socialLinkDetails
+                    ?.filter(l => !l.hasNewTab)
+                    .map(l => l.platform)
+                    .slice(0, 5);
+                return createResult({ id: 'social-links-new-tab', name: 'Social Links New Tab', category: 'og', severity: 'info' }, 'info', `${ctx.socialLinksWithoutNewTab} social link(s) don't open in new tab`, {
+                    recommendation: 'Consider using target="_blank" for social links to keep users on your site',
+                    evidence: {
+                        found: ctx.socialLinksWithoutNewTab,
+                        expected: 'Social links typically open in new tabs',
+                        impact: 'Users leaving your site may not return; opening in new tab preserves their session',
+                        example: '<a href="https://twitter.com/..." target="_blank" rel="noopener noreferrer">',
+                        issue: linksWithoutNewTab?.length ? `Without new tab: ${linksWithoutNewTab.join(', ')}` : undefined,
+                    },
+                });
+            }
+            return createResult({ id: 'social-links-new-tab', name: 'Social Links New Tab', category: 'og', severity: 'info' }, 'pass', 'All social links open in new tabs');
+        },
+    },
+    {
+        id: 'social-links-placement',
+        name: 'Social Links Placement',
+        category: 'og',
+        severity: 'info',
+        description: 'Social links should be placed in header or footer for easy discovery',
+        check: (ctx) => {
+            if (!ctx.totalSocialLinks || ctx.totalSocialLinks === 0) {
+                return createResult({ id: 'social-links-placement', name: 'Social Links Placement', category: 'og', severity: 'info' }, 'info', 'Not applicable (no social links found)', { recommendation: 'This rule checks social link placement when present' });
+            }
+            if (ctx.socialLinksInHeader === undefined && ctx.socialLinksInFooter === undefined) {
+                return createResult({ id: 'social-links-placement', name: 'Social Links Placement', category: 'og', severity: 'info' }, 'info', 'Not applicable (social link placement not checked)', { recommendation: 'This rule checks social link placement when data is available' });
+            }
+            const inHeaderOrFooter = (ctx.socialLinksInHeader || 0) + (ctx.socialLinksInFooter || 0);
+            if (inHeaderOrFooter === 0) {
+                return createResult({ id: 'social-links-placement', name: 'Social Links Placement', category: 'og', severity: 'info' }, 'info', 'Social links not found in header or footer', {
+                    recommendation: 'Place social media links in header or footer for consistent visibility',
+                    evidence: {
+                        found: 'Social links only in body content',
+                        expected: 'Social links in header and/or footer',
+                        impact: 'Users expect to find social links in standard locations; hidden links reduce engagement',
+                    },
+                });
+            }
+            const locations = [];
+            if (ctx.socialLinksInHeader && ctx.socialLinksInHeader > 0)
+                locations.push(`header (${ctx.socialLinksInHeader})`);
+            if (ctx.socialLinksInFooter && ctx.socialLinksInFooter > 0)
+                locations.push(`footer (${ctx.socialLinksInFooter})`);
+            return createResult({ id: 'social-links-placement', name: 'Social Links Placement', category: 'og', severity: 'info' }, 'pass', `Social links found in ${locations.join(' and ')}`);
+        },
+    },
+    {
+        id: 'social-links-diversity',
+        name: 'Social Platform Diversity',
+        category: 'og',
+        severity: 'info',
+        description: 'Consider linking to multiple social platforms for broader reach',
+        check: (ctx) => {
+            if (!ctx.platformsFound || ctx.platformsFound.length === 0) {
+                return createResult({ id: 'social-links-diversity', name: 'Social Platform Diversity', category: 'og', severity: 'info' }, 'info', 'Not applicable (no social platforms found)', { recommendation: 'This rule checks social platform diversity when social links are present' });
+            }
+            const majorPlatforms = ['facebook', 'twitter', 'instagram', 'linkedin', 'youtube'];
+            const foundMajor = ctx.platformsFound.filter(p => majorPlatforms.includes(p));
+            if (ctx.platformsFound.length === 1) {
+                return createResult({ id: 'social-links-diversity', name: 'Social Platform Diversity', category: 'og', severity: 'info' }, 'info', `Only 1 social platform linked: ${ctx.platformsFound[0]}`, {
+                    recommendation: 'Consider linking to additional relevant social platforms',
+                    evidence: {
+                        found: ctx.platformsFound,
+                        expected: 'Multiple social platforms for broader audience reach',
+                        impact: 'Different audiences prefer different platforms; diversification increases reach',
+                    },
+                });
+            }
+            if (foundMajor.length >= 2) {
+                return createResult({ id: 'social-links-diversity', name: 'Social Platform Diversity', category: 'og', severity: 'info' }, 'pass', `Found ${ctx.platformsFound.length} social platform(s): ${ctx.platformsFound.slice(0, 5).join(', ')}`, { evidence: { found: ctx.platformsFound } });
+            }
+            return createResult({ id: 'social-links-diversity', name: 'Social Platform Diversity', category: 'og', severity: 'info' }, 'info', `${ctx.platformsFound.length} social platform(s) linked`, {
+                evidence: { found: ctx.platformsFound },
+                recommendation: 'Consider adding major platforms like Facebook, Twitter/X, LinkedIn, or Instagram',
+            });
+        },
+    },
+    {
+        id: 'social-profile-consistency',
+        name: 'Social Profile Consistency',
+        category: 'og',
+        severity: 'info',
+        description: 'Social meta tags should be consistent with actual social profile links',
+        check: (ctx) => {
+            if (!ctx.twitterSite && !ctx.platformsFound?.includes('twitter')) {
+                return createResult({ id: 'social-profile-consistency', name: 'Social Profile Consistency', category: 'og', severity: 'info' }, 'info', 'Not applicable (no Twitter meta or links)', { recommendation: 'This rule checks consistency between social meta tags and profile links' });
+            }
+            const hasTwitterMeta = !!ctx.twitterSite;
+            const hasTwitterLink = ctx.platformsFound?.includes('twitter');
+            if (hasTwitterMeta && !hasTwitterLink) {
+                return createResult({ id: 'social-profile-consistency', name: 'Social Profile Consistency', category: 'og', severity: 'info' }, 'info', 'twitter:site is set but no Twitter profile link found', {
+                    recommendation: 'Add a link to your Twitter profile for consistency',
+                    evidence: {
+                        found: `twitter:site: ${ctx.twitterSite}`,
+                        expected: 'Matching Twitter profile link on page',
+                        impact: 'Users may want to follow your Twitter account directly from your site',
+                    },
+                });
+            }
+            if (!hasTwitterMeta && hasTwitterLink) {
+                return createResult({ id: 'social-profile-consistency', name: 'Social Profile Consistency', category: 'og', severity: 'info' }, 'info', 'Twitter profile linked but twitter:site meta tag is missing', {
+                    recommendation: 'Add twitter:site meta tag for proper Twitter Card attribution',
+                    evidence: {
+                        expected: '<meta name="twitter:site" content="@yourusername">',
+                        impact: 'Twitter Cards will not show your @username when shared',
+                    },
+                });
+            }
+            return createResult({ id: 'social-profile-consistency', name: 'Social Profile Consistency', category: 'og', severity: 'info' }, 'pass', 'Social meta tags are consistent with profile links');
+        },
+    },
 ];

package/dist/seo/rules/structural.js

@@ -8,13 +8,31 @@ export const structuralRules = [
         severity: 'error',
         description: 'Page must have exactly one H1 heading',
         check: (ctx) => {
-            if (ctx.h1Count === undefined)
-                return null;
+            if (ctx.h1Count === undefined) {
+                return createResult({ id: 'h1-exists', name: 'H1 Tag', category: 'headings', severity: 'error' }, 'info', 'Unable to check H1 (data unavailable)', { recommendation: 'Ensure HTML content is properly parsed' });
+            }
             if (ctx.h1Count === 0) {
-                return createResult({ id: 'h1-exists', name: 'H1 Tag', category: 'headings', severity: 'error' }, 'fail', 'Missing H1 heading', { recommendation: 'Add a single H1 heading that describes the page content' });
+                return createResult({ id: 'h1-exists', name: 'H1 Tag', category: 'headings', severity: 'error' }, 'fail', 'Missing H1 heading', {
+                    recommendation: 'Add a single H1 heading. It should be the main headline and include your primary keyword.',
+                    evidence: {
+                        found: 'No H1 tags detected on the page',
+                        expected: 'Exactly one <h1> tag',
+                        impact: 'The H1 tag is the most important heading for SEO. It tells search engines and users what the main topic of the page is. Pages without an H1 have poor semantic structure and may rank lower.',
+                        example: '<h1>Your Main Page Title Here</h1>'
+                    }
+                });
             }
             if (ctx.h1Count > 1) {
-                return createResult({ id: 'h1-exists', name: 'H1 Tag', category: 'headings', severity: 'error' }, 'warn', `Multiple H1 tags (${ctx.h1Count} found)`, { value: ctx.h1Count, recommendation: 'Use only one H1 per page' });
+                return createResult({ id: 'h1-exists', name: 'H1 Tag', category: 'headings', severity: 'error' }, 'warn', `Multiple H1 tags (${ctx.h1Count} found)`, {
+                    value: ctx.h1Count,
+                    recommendation: 'Use only one H1 per page to clearly signal the main topic.',
+                    evidence: {
+                        found: `${ctx.h1Count} H1 tags on the page`,
+                        expected: 'Exactly one <h1> tag',
+                        impact: 'Multiple H1 tags dilute the main topic signal and confuse search engines about which heading is the primary page title. This can hurt topical relevance and rankings.',
+                        example: '<h1>Main Title</h1>\n<!-- Use H2 for subtopics instead -->\n<h2>Subtopic One</h2>\n<h2>Subtopic Two</h2>'
+                    }
+                });
             }
             return createResult({ id: 'h1-exists', name: 'H1 Tag', category: 'headings', severity: 'error' }, 'pass', 'Single H1 tag present');
         },
@@ -26,15 +44,34 @@ export const structuralRules = [
         severity: 'warning',
         description: 'H1 should be 20-70 characters',
         check: (ctx) => {
-            if (!ctx.h1Text)
-                return null;
+            if (!ctx.h1Text) {
+                return createResult({ id: 'h1-length', name: 'H1 Length', category: 'headings', severity: 'warning' }, 'info', 'No H1 text to analyze', { recommendation: 'First add an H1 heading to the page' });
+            }
             const len = ctx.h1Length ?? ctx.h1Text.length;
             const { minLength, maxLength } = SEO_THRESHOLDS.headings.h1;
             if (len < minLength) {
-                return createResult({ id: 'h1-length', name: 'H1 Length', category: 'headings', severity: 'warning' }, 'warn', `H1 too short (${len} chars, min: ${minLength})`, { value: len, recommendation: `Expand H1 to at least ${minLength} characters` });
+                return createResult({ id: 'h1-length', name: 'H1 Length', category: 'headings', severity: 'warning' }, 'warn', `H1 too short (${len} chars, min: ${minLength})`, {
+                    value: len,
+                    recommendation: `Expand H1 to at least ${minLength} characters`,
+                    evidence: {
+                        found: `H1 with ${len} characters: "${ctx.h1Text}"`,
+                        expected: `${minLength}-${maxLength} characters`,
+                        impact: 'Very short H1 tags may not provide enough context for search engines and users to understand the page topic. Descriptive H1s improve relevance signals and click-through rates.',
+                        example: '<h1>Complete Guide to SEO Best Practices</h1>'
+                    }
+                });
             }
             if (len > maxLength) {
-                return createResult({ id: 'h1-length', name: 'H1 Length', category: 'headings', severity: 'warning' }, 'warn', `H1 too long (${len} chars, max: ${maxLength})`, { value: len, recommendation: `Shorten H1 to under ${maxLength} characters` });
+                return createResult({ id: 'h1-length', name: 'H1 Length', category: 'headings', severity: 'warning' }, 'warn', `H1 too long (${len} chars, max: ${maxLength})`, {
+                    value: len,
+                    recommendation: `Shorten H1 to under ${maxLength} characters`,
+                    evidence: {
+                        found: `H1 with ${len} characters: "${ctx.h1Text}"`,
+                        expected: `${minLength}-${maxLength} characters`,
+                        impact: 'Overly long H1 tags can be truncated in search results and may appear unfocused. Concise H1s are more scannable and effective for both users and search engines.',
+                        example: '<h1>SEO Guide: On-Page Optimization Tips</h1>'
+                    }
+                });
             }
             return createResult({ id: 'h1-length', name: 'H1 Length', category: 'headings', severity: 'warning' }, 'pass', `H1 length OK (${len} chars)`, { value: len });
         },
@@ -46,11 +83,20 @@ export const structuralRules = [
         severity: 'warning',
         description: 'Headings should follow sequential order (H1 → H2 → H3)',
         check: (ctx) => {
-            if (ctx.headingHierarchyValid === undefined)
-                return null;
+            if (ctx.headingHierarchyValid === undefined) {
+                return createResult({ id: 'heading-hierarchy', name: 'Heading Hierarchy', category: 'headings', severity: 'warning' }, 'info', 'Unable to check heading hierarchy (data unavailable)', { recommendation: 'Ensure heading analysis completed' });
+            }
             if (!ctx.headingHierarchyValid) {
                 const skipped = ctx.headingSkippedLevels?.join(', ') || 'unknown';
-                return createResult({ id: 'heading-hierarchy', name: 'Heading Hierarchy', category: 'headings', severity: 'warning' }, 'warn', `Heading levels are skipped (${skipped})`, { recommendation: 'Use sequential heading levels (H1 → H2 → H3)' });
+                return createResult({ id: 'heading-hierarchy', name: 'Heading Hierarchy', category: 'headings', severity: 'warning' }, 'warn', `Heading levels are skipped (${skipped})`, {
+                    recommendation: 'Use sequential heading levels (H1 → H2 → H3)',
+                    evidence: {
+                        found: `Skipped heading levels: ${skipped}`,
+                        expected: 'Sequential heading structure (H1 → H2 → H3 → H4, etc.)',
+                        impact: 'Skipping heading levels disrupts the document outline and can confuse screen readers and search engine crawlers trying to understand content hierarchy. This weakens accessibility and semantic structure.',
+                        example: '<h1>Main Title</h1>\n<h2>Section Title</h2>\n<h3>Subsection Title</h3>\n<!-- Do NOT skip from H1 to H3 -->'
+                    }
+                });
             }
             return createResult({ id: 'heading-hierarchy', name: 'Heading Hierarchy', category: 'headings', severity: 'warning' }, 'pass', 'Heading structure is correct');
         },
@@ -62,8 +108,9 @@ export const structuralRules = [
         severity: 'info',
         description: 'Page should have 2-8 H2 headings for good structure',
         check: (ctx) => {
-            if (ctx.h2Count === undefined)
-                return null;
+            if (ctx.h2Count === undefined) {
+                return createResult({ id: 'h2-count', name: 'H2 Count', category: 'headings', severity: 'info' }, 'info', 'Unable to check H2 count (data unavailable)', { recommendation: 'Ensure heading analysis completed' });
+            }
             const { min, max } = SEO_THRESHOLDS.headings.h2;
             if (ctx.h2Count < min) {
                 return createResult({ id: 'h2-count', name: 'H2 Count', category: 'headings', severity: 'info' }, 'info', `Few H2 headings (${ctx.h2Count})`, { value: ctx.h2Count, recommendation: `Consider adding more H2 headings for better structure (${min}-${max} ideal)` });
@@ -84,7 +131,7 @@ export const structuralRules = [
             if (!ctx.hasHeader) {
                 return createResult({ id: 'html5-header-exists', name: 'HTML5 Header', category: 'technical', severity: 'info' }, 'info', 'Missing <header> element', { recommendation: 'Use <header> for site-wide or page-specific introductory content' });
             }
-            return null;
+            return createResult({ id: 'html5-header-exists', name: 'HTML5 Header', category: 'technical', severity: 'info' }, 'pass', 'HTML5 <header> element present');
         },
     },
     {
@@ -97,7 +144,7 @@ export const structuralRules = [
             if (!ctx.hasNav) {
                 return createResult({ id: 'html5-nav-exists', name: 'HTML5 Navigation', category: 'technical', severity: 'info' }, 'info', 'Missing <nav> element', { recommendation: 'Use <nav> to define a block of navigation links' });
             }
-            return null;
+            return createResult({ id: 'html5-nav-exists', name: 'HTML5 Navigation', category: 'technical', severity: 'info' }, 'pass', 'HTML5 <nav> element present');
         },
     },
     {
@@ -110,7 +157,7 @@ export const structuralRules = [
             if (!ctx.hasMain) {
                 return createResult({ id: 'html5-main-exists', name: 'HTML5 Main Content', category: 'technical', severity: 'info' }, 'info', 'Missing <main> element', { recommendation: 'Use <main> to enclose the dominant content of the <body>' });
             }
-            return null;
+            return createResult({ id: 'html5-main-exists', name: 'HTML5 Main Content', category: 'technical', severity: 'info' }, 'pass', 'HTML5 <main> element present');
         },
     },
     {
@@ -123,7 +170,7 @@ export const structuralRules = [
             if (!ctx.hasArticle && ctx.wordCount && ctx.wordCount > 500) {
                 return createResult({ id: 'html5-article-exists', name: 'HTML5 Article', category: 'technical', severity: 'info' }, 'info', 'Missing <article> element for substantial content', { recommendation: 'Consider using <article> for blog posts, news articles, etc.' });
             }
-            return null;
+            return createResult({ id: 'html5-article-exists', name: 'HTML5 Article', category: 'technical', severity: 'info' }, 'pass', 'HTML5 <article> element present or not required');
         },
     },
     {
@@ -136,7 +183,7 @@ export const structuralRules = [
             if (!ctx.hasSection && (ctx.h2Count && ctx.h2Count > 1)) {
                 return createResult({ id: 'html5-section-exists', name: 'HTML5 Section', category: 'technical', severity: 'info' }, 'info', 'Missing <section> element for content grouping', { recommendation: 'Consider using <section> to group related content, usually with a heading' });
             }
-            return null;
+            return createResult({ id: 'html5-section-exists', name: 'HTML5 Section', category: 'technical', severity: 'info' }, 'pass', 'HTML5 <section> element present or not required');
         },
     },
     {
@@ -149,7 +196,28 @@ export const structuralRules = [
             if (!ctx.hasFooter) {
                 return createResult({ id: 'html5-footer-exists', name: 'HTML5 Footer', category: 'technical', severity: 'info' }, 'info', 'Missing <footer> element', { recommendation: 'Use <footer> for site-wide or page-specific footer content' });
             }
-            return null;
+            return createResult({ id: 'html5-footer-exists', name: 'HTML5 Footer', category: 'technical', severity: 'info' }, 'pass', 'HTML5 <footer> element present');
+        },
+    },
+    {
+        id: 'keywords-in-h1',
+        name: 'Keywords in H1',
+        category: 'headings',
+        severity: 'warning',
+        description: 'H1 should contain main keywords',
+        check: (ctx) => {
+            if (ctx.keywordsInH1 === false && ctx.topKeywords && ctx.topKeywords.length > 0) {
+                return createResult({ id: 'keywords-in-h1', name: 'Keywords in H1', category: 'headings', severity: 'warning' }, 'warn', 'H1 does not appear to contain top keywords', {
+                    recommendation: 'Ensure your H1 tag includes your main target keyword naturally.',
+                    evidence: {
+                        found: `H1: "${ctx.h1Text}"`,
+                        expected: `Should contain one of: ${ctx.topKeywords.join(', ')}`,
+                        impact: 'Keywords in H1 confirm relevance to the user and search engines. The H1 should naturally include your primary target keyword to reinforce the page topic and improve rankings for that term.',
+                        example: `<h1>Complete Guide to ${ctx.topKeywords?.[0] || 'Your Primary Keyword'}</h1>`
+                    }
+                });
+            }
+            return createResult({ id: 'keywords-in-h1', name: 'Keywords in H1', category: 'headings', severity: 'warning' }, 'pass', 'Keywords present in H1');
         },
     },
 ];