recker 1.0.43 → 1.0.44

package/dist/seo/rules/technical-advanced.js

@@ -7,8 +7,9 @@ export const technicalAdvancedRules = [
         severity: 'warning',
         description: 'Pages should not use meta refresh redirects',
         check: (ctx) => {
-            if (!ctx.metaRefresh)
-                return null;
+            if (!ctx.metaRefresh) {
+                return createResult({ id: 'meta-refresh-redirect', name: 'Meta Refresh Redirect', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no meta refresh detected)', { recommendation: 'This rule checks for meta refresh redirects which can impact SEO' });
+            }
             const { delay, url } = ctx.metaRefresh;
             if (url) {
                 return createResult({ id: 'meta-refresh-redirect', name: 'Meta Refresh Redirect', category: 'technical', severity: 'warning' }, delay === 0 ? 'warn' : 'fail', `Page uses meta refresh redirect (${delay}s delay)`, {
@@ -35,7 +36,7 @@ export const technicalAdvancedRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'meta-refresh-redirect', name: 'Meta Refresh Redirect', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no meta refresh detected)', { recommendation: 'This rule checks for meta refresh redirects which can impact SEO' });
         },
     },
     {
@@ -45,8 +46,9 @@ export const technicalAdvancedRules = [
         severity: 'warning',
         description: 'HTML page should not exceed reasonable size limits',
         check: (ctx) => {
-            if (ctx.htmlSize === undefined)
-                return null;
+            if (ctx.htmlSize === undefined) {
+                return createResult({ id: 'html-page-size', name: 'HTML Page Size', category: 'performance', severity: 'warning' }, 'info', 'Not applicable (HTML size data unavailable)', { recommendation: 'This rule checks if HTML size is within recommended limits for optimal performance' });
+            }
             const sizeKb = ctx.htmlSize / 1024;
             const sizeMb = sizeKb / 1024;
             if (sizeMb > 2) {
@@ -81,8 +83,9 @@ export const technicalAdvancedRules = [
         severity: 'warning',
         description: 'Total page weight should be optimized for performance',
         check: (ctx) => {
-            if (ctx.totalPageSize === undefined)
-                return null;
+            if (ctx.totalPageSize === undefined) {
+                return createResult({ id: 'total-page-size', name: 'Total Page Size', category: 'performance', severity: 'warning' }, 'info', 'Not applicable (total page size data unavailable)', { recommendation: 'This rule checks total page weight including all resources for optimal load time' });
+            }
             const sizeMb = ctx.totalPageSize / (1024 * 1024);
             if (sizeMb > 5) {
                 return createResult({ id: 'total-page-size', name: 'Total Page Size', category: 'performance', severity: 'warning' }, 'fail', `Total page size ${sizeMb.toFixed(2)}MB exceeds 5MB`, {
@@ -117,8 +120,9 @@ export const technicalAdvancedRules = [
         description: 'Server should respond within acceptable time limits',
         check: (ctx) => {
             const ttfb = ctx.timings?.ttfb;
-            if (ttfb === undefined)
-                return null;
+            if (ttfb === undefined) {
+                return createResult({ id: 'server-response-time', name: 'Server Response Time', category: 'performance', severity: 'warning' }, 'info', 'Not applicable (TTFB timing data unavailable)', { recommendation: 'This rule checks server response time (TTFB) for performance optimization' });
+            }
             if (ttfb > 5000) {
                 return createResult({ id: 'server-response-time', name: 'Server Response Time', category: 'performance', severity: 'warning' }, 'fail', `TTFB ${(ttfb / 1000).toFixed(2)}s exceeds 5s`, {
                     value: ttfb,
@@ -151,8 +155,9 @@ export const technicalAdvancedRules = [
         severity: 'warning',
         description: 'URLs should not be excessively long',
         check: (ctx) => {
-            if (!ctx.url)
-                return null;
+            if (!ctx.url) {
+                return createResult({ id: 'url-length', name: 'URL Length', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (URL data unavailable)', { recommendation: 'This rule checks URL length to ensure it is within recommended limits' });
+            }
             const length = ctx.url.length;
             if (length > 2000) {
                 return createResult({ id: 'url-length', name: 'URL Length', category: 'technical', severity: 'warning' }, 'fail', `URL length ${length} chars exceeds browser limits`, {
@@ -186,8 +191,9 @@ export const technicalAdvancedRules = [
         severity: 'warning',
         description: 'URLs should not contain problematic special characters',
         check: (ctx) => {
-            if (!ctx.url)
-                return null;
+            if (!ctx.url) {
+                return createResult({ id: 'url-special-chars', name: 'URL Special Characters', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (URL data unavailable)', { recommendation: 'This rule checks for problematic special characters in URLs' });
+            }
             try {
                 const urlObj = new URL(ctx.url);
                 const path = urlObj.pathname + urlObj.search;
@@ -224,8 +230,9 @@ export const technicalAdvancedRules = [
                     recommendation: 'Fix URL syntax',
                     evidence: {
                         found: ctx.url,
-                        expected: 'Valid URL',
-                        impact: 'Invalid URLs cannot be crawled or indexed'
+                        expected: 'Valid URL format (e.g., https://example.com/path)',
+                        impact: 'Invalid URLs cannot be crawled or indexed',
+                        example: 'https://example.com/valid-path-with-hyphens',
                     }
                 });
             }
@@ -238,8 +245,9 @@ export const technicalAdvancedRules = [
         severity: 'error',
         description: 'Pages with password fields must use HTTPS',
         check: (ctx) => {
-            if (!ctx.hasPasswordField || ctx.isHttps === undefined)
-                return null;
+            if (!ctx.hasPasswordField || ctx.isHttps === undefined) {
+                return createResult({ id: 'password-on-http', name: 'Password Fields on HTTP', category: 'security', severity: 'error' }, 'info', 'Not applicable (no password fields detected)', { recommendation: 'This rule ensures password fields are served over HTTPS for security' });
+            }
             if (ctx.hasPasswordField && !ctx.isHttps) {
                 return createResult({ id: 'password-on-http', name: 'Password Fields on HTTP', category: 'security', severity: 'error' }, 'fail', 'Password field detected on non-HTTPS page', {
                     recommendation: 'Serve login/registration pages over HTTPS only',
@@ -251,10 +259,7 @@ export const technicalAdvancedRules = [
                     }
                 });
             }
-            if (ctx.hasPasswordField && ctx.isHttps) {
-                return createResult({ id: 'password-on-http', name: 'Password Fields on HTTP', category: 'security', severity: 'error' }, 'pass', 'Password field properly served over HTTPS');
-            }
-            return null;
+            return createResult({ id: 'password-on-http', name: 'Password Fields on HTTP', category: 'security', severity: 'error' }, 'pass', 'Password field properly served over HTTPS');
         },
     },
     {
@@ -264,8 +269,9 @@ export const technicalAdvancedRules = [
         severity: 'warning',
         description: 'Forms should submit data over HTTPS',
         check: (ctx) => {
-            if (ctx.formsOnHttp === undefined)
-                return null;
+            if (ctx.formsOnHttp === undefined) {
+                return createResult({ id: 'forms-on-http', name: 'Forms on HTTP', category: 'security', severity: 'warning' }, 'info', 'Not applicable (form data unavailable)', { recommendation: 'This rule checks if forms submit data over secure HTTPS connections' });
+            }
             if (ctx.formsOnHttp > 0) {
                 return createResult({ id: 'forms-on-http', name: 'Forms on HTTP', category: 'security', severity: 'warning' }, 'warn', `${ctx.formsOnHttp} form(s) submit to HTTP URLs`, {
                     value: ctx.formsOnHttp,
@@ -277,7 +283,7 @@ export const technicalAdvancedRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'forms-on-http', name: 'Forms on HTTP', category: 'security', severity: 'warning' }, 'pass', 'All forms submit over HTTPS or no forms detected');
         },
     },
 ];

package/dist/seo/rules/technical.js

@@ -8,7 +8,16 @@ export const technicalRules = [
         description: 'Page should have a canonical URL',
         check: (ctx) => {
             if (!ctx.hasCanonical) {
-                return createResult({ id: 'canonical-exists', name: 'Canonical URL', category: 'technical', severity: 'warning' }, 'warn', 'No canonical URL defined', { recommendation: 'Add <link rel="canonical" href="..."> to prevent duplicate content' });
+                return createResult({ id: 'canonical-exists', name: 'Canonical URL', category: 'technical', severity: 'warning' }, 'warn', 'No canonical URL defined', {
+                    recommendation: 'Add a canonical URL to indicate the preferred version of this page.',
+                    evidence: {
+                        found: 'No <link rel="canonical"> tag',
+                        expected: 'A canonical URL pointing to the preferred version',
+                        impact: 'Without canonical, search engines may split ranking signals across duplicate URLs (www vs non-www, HTTP vs HTTPS, with/without trailing slash).',
+                        example: '<link rel="canonical" href="https://example.com/page/">',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/canonicalization'
+                    }
+                });
             }
             return createResult({ id: 'canonical-exists', name: 'Canonical URL', category: 'technical', severity: 'warning' }, 'pass', 'Canonical URL is defined', { value: ctx.canonicalUrl });
         },
@@ -21,7 +30,16 @@ export const technicalRules = [
         description: 'HTML should have lang attribute',
         check: (ctx) => {
             if (!ctx.hasLang) {
-                return createResult({ id: 'lang-exists', name: 'Language', category: 'technical', severity: 'warning' }, 'warn', 'Missing lang attribute on <html>', { recommendation: 'Add lang attribute: <html lang="en">' });
+                return createResult({ id: 'lang-exists', name: 'Language', category: 'technical', severity: 'warning' }, 'warn', 'Missing lang attribute on <html>', {
+                    recommendation: 'Declare the page language for better accessibility and SEO.',
+                    evidence: {
+                        found: '<html> tag without lang attribute',
+                        expected: '<html lang="en"> (or appropriate language code)',
+                        impact: 'The lang attribute helps screen readers pronounce content correctly and helps search engines serve the right audience. It\'s required for WCAG accessibility compliance.',
+                        example: '<html lang="en">\n<html lang="pt-BR">\n<html lang="es">',
+                        learnMore: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang'
+                    }
+                });
             }
             return createResult({ id: 'lang-exists', name: 'Language', category: 'technical', severity: 'warning' }, 'pass', `Language attribute set (${ctx.langValue})`);
         },
@@ -34,10 +52,27 @@ export const technicalRules = [
         description: 'Page should declare character encoding',
         check: (ctx) => {
             if (!ctx.hasCharset) {
-                return createResult({ id: 'charset-exists', name: 'Charset', category: 'technical', severity: 'warning' }, 'warn', 'Missing charset declaration', { recommendation: 'Add <meta charset="UTF-8"> in <head>' });
+                return createResult({ id: 'charset-exists', name: 'Charset', category: 'technical', severity: 'warning' }, 'warn', 'Missing charset declaration', {
+                    recommendation: 'Declare character encoding to ensure proper text rendering.',
+                    evidence: {
+                        found: 'No charset meta tag',
+                        expected: '<meta charset="UTF-8"> as the first element in <head>',
+                        impact: 'Without charset declaration, browsers may guess incorrectly, causing garbled text (mojibake). UTF-8 supports all languages and special characters.',
+                        example: '<head>\n  <meta charset="UTF-8">\n  <!-- other tags -->\n</head>',
+                        learnMore: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#charset'
+                    }
+                });
             }
             if (ctx.charset && ctx.charset.toLowerCase() !== 'utf-8') {
-                return createResult({ id: 'charset-exists', name: 'Charset', category: 'technical', severity: 'warning' }, 'warn', `Non-UTF-8 charset: ${ctx.charset}`, { recommendation: 'Use UTF-8 charset for best compatibility' });
+                return createResult({ id: 'charset-exists', name: 'Charset', category: 'technical', severity: 'warning' }, 'warn', `Non-UTF-8 charset: ${ctx.charset}`, {
+                    recommendation: 'Switch to UTF-8 encoding for universal compatibility.',
+                    evidence: {
+                        found: `charset="${ctx.charset}"`,
+                        expected: 'charset="UTF-8"',
+                        impact: 'UTF-8 is the standard encoding that supports all languages. Legacy encodings like ISO-8859-1 or Windows-1252 cannot display all characters.',
+                        learnMore: 'https://www.w3.org/International/questions/qa-choosing-encodings'
+                    }
+                });
             }
             return createResult({ id: 'charset-exists', name: 'Charset', category: 'technical', severity: 'warning' }, 'pass', 'UTF-8 charset declared');
         },
@@ -49,10 +84,21 @@ export const technicalRules = [
         severity: 'warning',
         description: 'Check if page is set to noindex',
         check: (ctx) => {
-            if (!ctx.metaRobots || ctx.metaRobots.length === 0)
-                return null;
+            if (!ctx.metaRobots || ctx.metaRobots.length === 0) {
+                return createResult({ id: 'robots-noindex', name: 'Robots', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no robots meta tag)', { recommendation: 'This rule checks for noindex directive in robots meta tag' });
+            }
             if (ctx.metaRobots.includes('noindex')) {
-                return createResult({ id: 'robots-noindex', name: 'Robots', category: 'technical', severity: 'warning' }, 'warn', 'Page is set to noindex', { value: ctx.metaRobots.join(', '), recommendation: 'Remove noindex if you want the page to be indexed' });
+                return createResult({ id: 'robots-noindex', name: 'Robots', category: 'technical', severity: 'warning' }, 'warn', 'Page is set to noindex', {
+                    value: ctx.metaRobots.join(', '),
+                    recommendation: 'Verify that noindex is intentional. This page will NOT appear in search results.',
+                    evidence: {
+                        found: `<meta name="robots" content="${ctx.metaRobots.join(', ')}">`,
+                        expected: 'No noindex directive (for pages you want indexed)',
+                        impact: 'The noindex directive completely prevents this page from appearing in Google, Bing, and other search engines. This is useful for thank-you pages or admin areas, but harmful if applied accidentally.',
+                        example: 'To allow indexing: <meta name="robots" content="index, follow">',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/block-indexing'
+                    }
+                });
             }
             return createResult({ id: 'robots-noindex', name: 'Robots', category: 'technical', severity: 'info' }, 'info', `Robots meta: ${ctx.metaRobots.join(', ')}`);
         },
@@ -65,7 +111,16 @@ export const technicalRules = [
         description: 'Page should have a favicon defined',
         check: (ctx) => {
             if (!ctx.hasFavicon) {
-                return createResult({ id: 'favicon-exists', name: 'Favicon', category: 'technical', severity: 'warning' }, 'warn', 'No favicon defined', { recommendation: 'Add <link rel="icon" href="/favicon.ico"> for browser tab icon' });
+                return createResult({ id: 'favicon-exists', name: 'Favicon', category: 'technical', severity: 'warning' }, 'warn', 'No favicon defined', {
+                    recommendation: 'Add a favicon to improve brand recognition and user experience.',
+                    evidence: {
+                        found: 'No favicon link tag',
+                        expected: '<link rel="icon"> pointing to your favicon',
+                        impact: 'Favicons appear in browser tabs, bookmarks, history, and search results. Missing favicons look unprofessional and generate 404 errors in server logs.',
+                        example: '<link rel="icon" href="/favicon.ico" sizes="32x32">\n<link rel="icon" href="/icon.svg" type="image/svg+xml">\n<link rel="apple-touch-icon" href="/apple-touch-icon.png">',
+                        learnMore: 'https://web.dev/articles/add-manifest#icons'
+                    }
+                });
             }
             return createResult({ id: 'favicon-exists', name: 'Favicon', category: 'technical', severity: 'warning' }, 'pass', 'Favicon is defined', { value: ctx.faviconUrl });
         },
@@ -78,9 +133,18 @@ export const technicalRules = [
         description: 'URLs should be lowercase for consistency',
         check: (ctx) => {
             if (ctx.urlHasUppercase) {
-                return createResult({ id: 'url-lowercase', name: 'URL Lowercase', category: 'technical', severity: 'warning' }, 'warn', 'URL contains uppercase characters', { recommendation: 'Use lowercase URLs for better SEO consistency' });
+                return createResult({ id: 'url-lowercase', name: 'URL Lowercase', category: 'technical', severity: 'warning' }, 'warn', 'URL contains uppercase characters', {
+                    recommendation: 'Convert URL to lowercase for consistency and to avoid duplicate content.',
+                    evidence: {
+                        found: ctx.url,
+                        expected: 'All lowercase URL path',
+                        impact: 'URLs are case-sensitive on most servers. /Page and /page are different URLs, which can split ranking signals and cause duplicate content issues.',
+                        example: 'Instead of /About-Us, use /about-us',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/url-structure'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'url-lowercase', name: 'URL Lowercase', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (URL is properly lowercase)', { recommendation: 'This rule ensures URLs use lowercase to avoid duplicate content issues' });
         },
     },
     {
@@ -96,9 +160,18 @@ export const technicalRules = [
                     issues.push('accents');
                 if (ctx.urlHasSpecialChars)
                     issues.push('special characters');
-                return createResult({ id: 'url-clean', name: 'URL Clean', category: 'technical', severity: 'warning' }, 'warn', `URL contains ${issues.join(' and ')}`, { recommendation: 'Use clean URLs without accents or special characters' });
+                return createResult({ id: 'url-clean', name: 'URL Clean', category: 'technical', severity: 'warning' }, 'warn', `URL contains ${issues.join(' and ')}`, {
+                    recommendation: 'Use clean, ASCII-only URLs for maximum compatibility.',
+                    evidence: {
+                        found: ctx.url,
+                        expected: 'URL with only letters, numbers, and hyphens',
+                        impact: 'Accented characters and special characters get percent-encoded (%C3%A9 instead of é), making URLs ugly and hard to share. Some systems may not handle them correctly.',
+                        example: 'Instead of /café-menü, use /cafe-menu',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/url-structure'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'url-clean', name: 'URL Clean', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (URL is clean)', { recommendation: 'This rule checks for accents and special characters in URLs' });
         },
     },
     {
@@ -108,17 +181,28 @@ export const technicalRules = [
         severity: 'warning',
         description: 'URLs should not contain query parameters',
         check: (ctx) => {
-            if (!ctx.url)
-                return null;
+            if (!ctx.url) {
+                return createResult({ id: 'url-no-params', name: 'URL Parameters', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (URL data unavailable)', { recommendation: 'This rule checks for query parameters that can cause duplicate content' });
+            }
             try {
                 const urlObj = new URL(ctx.url);
                 if (urlObj.search && urlObj.search.length > 1) {
-                    return createResult({ id: 'url-no-params', name: 'URL Parameters', category: 'technical', severity: 'warning' }, 'warn', 'URL contains query parameters', { value: urlObj.search, recommendation: 'Use clean URLs (rewritten paths) without query parameters' });
+                    return createResult({ id: 'url-no-params', name: 'URL Parameters', category: 'technical', severity: 'warning' }, 'warn', 'URL contains query parameters', {
+                        value: urlObj.search,
+                        recommendation: 'Consider using clean, path-based URLs instead of query parameters.',
+                        evidence: {
+                            found: urlObj.search,
+                            expected: 'Clean URL without query strings',
+                            impact: 'Query parameters make URLs harder to read and share. Google recommends using simple, descriptive URLs. Parameters can also cause crawl budget waste if they create many URL variations.',
+                            example: 'Instead of /products?category=shoes&color=red\nUse /products/shoes/red',
+                            learnMore: 'https://developers.google.com/search/docs/crawling-indexing/url-structure#use-simple-urls'
+                        }
+                    });
                 }
             }
             catch {
             }
-            return null;
+            return createResult({ id: 'url-no-params', name: 'URL Parameters', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no query parameters)', { recommendation: 'Clean URLs without parameters are preferred for SEO' });
         },
     },
     {
@@ -128,14 +212,24 @@ export const technicalRules = [
         severity: 'warning',
         description: 'Check for restrictive meta robots directives like noindex, nofollow, noarchive etc.',
         check: (ctx) => {
-            if (!ctx.metaRobots || ctx.metaRobots.length === 0)
-                return null;
+            if (!ctx.metaRobots || ctx.metaRobots.length === 0) {
+                return createResult({ id: 'technical-meta-robots-directives', name: 'Meta Robots Directives', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no robots meta tag)', { recommendation: 'This rule checks for restrictive robots directives' });
+            }
             const restrictiveDirectives = ['noindex', 'nofollow', 'noarchive', 'nosnippet', 'noimageindex'];
             const foundRestrictive = ctx.metaRobots.filter(directive => restrictiveDirectives.includes(directive));
             if (foundRestrictive.length > 0) {
-                return createResult({ id: 'technical-meta-robots-directives', name: 'Meta Robots Directives', category: 'technical', severity: 'warning' }, 'warn', `Restrictive meta robots directives found: ${foundRestrictive.join(', ')}`, { recommendation: 'Ensure these directives are intentional to prevent unintended blocking of indexing or crawling.' });
+                return createResult({ id: 'technical-meta-robots-directives', name: 'Meta Robots Directives', category: 'technical', severity: 'warning' }, 'warn', `Restrictive meta robots directives found: ${foundRestrictive.join(', ')}`, {
+                    recommendation: 'Verify these restrictive directives are intentional.',
+                    evidence: {
+                        found: foundRestrictive.join(', '),
+                        expected: 'index, follow (for pages you want in search results)',
+                        impact: 'noindex: page won\'t appear in search. nofollow: links won\'t pass PageRank. noarchive: no cached version. nosnippet: no description in results. noimageindex: images not indexed.',
+                        example: 'To allow everything: <meta name="robots" content="index, follow, archive, snippet">',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'technical-meta-robots-directives', name: 'Meta Robots Directives', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no restrictive directives found)', { recommendation: 'Meta robots directives allow full indexing' });
         },
     },
     {
@@ -145,13 +239,21 @@ export const technicalRules = [
         severity: 'info',
         description: 'X-Robots-Tag header can be used to control indexing, especially for non-HTML content.',
         check: (ctx) => {
-            if (!ctx.responseHeaders)
-                return null;
+            if (!ctx.responseHeaders) {
+                return createResult({ id: 'technical-x-robots-tag', name: 'X-Robots-Tag Header', category: 'technical', severity: 'info' }, 'info', 'Not applicable (response headers unavailable)', { recommendation: 'This rule checks for X-Robots-Tag HTTP header' });
+            }
             const xRobotsTag = ctx.responseHeaders['x-robots-tag'] || ctx.responseHeaders['X-Robots-Tag'];
             if (xRobotsTag) {
-                return createResult({ id: 'technical-x-robots-tag', name: 'X-Robots-Tag Header', category: 'technical', severity: 'info' }, 'info', `X-Robots-Tag header found: ${xRobotsTag}`, { recommendation: 'Ensure X-Robots-Tag directives (e.g., noindex) are intentional.' });
+                return createResult({ id: 'technical-x-robots-tag', name: 'X-Robots-Tag Header', category: 'technical', severity: 'info' }, 'info', `X-Robots-Tag header found: ${xRobotsTag}`, {
+                    recommendation: 'Verify this server-level robots directive is intentional.',
+                    evidence: {
+                        found: `X-Robots-Tag: ${xRobotsTag}`,
+                        impact: 'X-Robots-Tag HTTP header works like meta robots but at server level. It\'s commonly used for non-HTML files (PDFs, images) but can also override meta tags for HTML pages.',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag#xrobotstag'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'technical-x-robots-tag', name: 'X-Robots-Tag Header', category: 'technical', severity: 'info' }, 'info', 'Not applicable (no X-Robots-Tag header)', { recommendation: 'X-Robots-Tag header is not present' });
         },
     },
     {
@@ -171,9 +273,18 @@ export const technicalRules = [
             if (!ctx.hasTermsOfServiceLink)
                 missingSignals.push('Terms of Service');
             if (missingSignals.length > 0) {
-                return createResult({ id: 'technical-trust-signals', name: 'Trust Signals (Links)', category: 'technical', severity: 'info' }, 'info', `Missing links to key trust pages: ${missingSignals.join(', ')}`, { recommendation: 'Add clear links to "About Us", "Contact", "Privacy Policy", and "Terms of Service" pages to build user and search engine trust.' });
+                return createResult({ id: 'technical-trust-signals', name: 'Trust Signals (Links)', category: 'technical', severity: 'info' }, 'info', `Missing links to key trust pages: ${missingSignals.join(', ')}`, {
+                    recommendation: 'Add links to trust-building pages to improve E-E-A-T signals.',
+                    evidence: {
+                        found: `Missing: ${missingSignals.join(', ')}`,
+                        expected: 'Links to About, Contact, Privacy Policy, and Terms of Service',
+                        impact: 'Google\'s E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) guidelines favor sites that clearly identify who they are. These pages are essential for YMYL (Your Money Your Life) sites.',
+                        example: '<footer>\n  <a href="/about">About Us</a>\n  <a href="/contact">Contact</a>\n  <a href="/privacy">Privacy Policy</a>\n  <a href="/terms">Terms of Service</a>\n</footer>',
+                        learnMore: 'https://developers.google.com/search/docs/fundamentals/creating-helpful-content'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'technical-trust-signals', name: 'Trust Signals (Links)', category: 'technical', severity: 'info' }, 'info', 'Not applicable (all trust signals present)', { recommendation: 'All key trust pages are linked' });
         },
     },
     {
@@ -183,13 +294,22 @@ export const technicalRules = [
         severity: 'info',
         description: 'A higher text to HTML ratio indicates more content relative to code, which is good for SEO.',
         check: (ctx) => {
-            if (ctx.textHtmlRatio === undefined)
-                return null;
+            if (ctx.textHtmlRatio === undefined) {
+                return createResult({ id: 'technical-text-html-ratio', name: 'Text/HTML Ratio', category: 'technical', severity: 'info' }, 'info', 'Not applicable (text/HTML ratio data unavailable)', { recommendation: 'This rule checks the ratio of visible text to HTML code' });
+            }
             const threshold = 15;
             if (ctx.textHtmlRatio < threshold) {
-                return createResult({ id: 'technical-text-html-ratio', name: 'Text/HTML Ratio', category: 'technical', severity: 'info' }, 'warn', `Low Text/HTML ratio: ${ctx.textHtmlRatio.toFixed(2)}% (target > ${threshold}%)`, { recommendation: 'Increase text content relative to HTML code. Reduce unnecessary markup, or add more textual content.' });
+                return createResult({ id: 'technical-text-html-ratio', name: 'Text/HTML Ratio', category: 'technical', severity: 'info' }, 'warn', `Low Text/HTML ratio: ${ctx.textHtmlRatio.toFixed(2)}% (target > ${threshold}%)`, {
+                    recommendation: 'Increase visible text content relative to HTML code.',
+                    evidence: {
+                        found: `${ctx.textHtmlRatio.toFixed(2)}% text content`,
+                        expected: `At least ${threshold}% text content`,
+                        impact: 'Pages with low text-to-HTML ratio may appear thin or low-quality to search engines. This can indicate excessive scripts, inline CSS, or insufficient content.',
+                        learnMore: 'https://developers.google.com/search/docs/fundamentals/creating-helpful-content#content-and-quality'
+                    }
+                });
             }
-            return null;
+            return createResult({ id: 'technical-text-html-ratio', name: 'Text/HTML Ratio', category: 'technical', severity: 'info' }, 'info', 'Not applicable (text/HTML ratio is good)', { recommendation: `Text/HTML ratio is ${ctx.textHtmlRatio.toFixed(2)}%, which is healthy` });
         },
     },
     {
@@ -199,7 +319,15 @@ export const technicalRules = [
         severity: 'info',
         description: 'Ensure a robots.txt file exists at the root of the domain to guide crawlers.',
         check: (ctx) => {
-            return createResult({ id: 'technical-robots-txt-hint', name: 'Robots.txt Hint', category: 'technical', severity: 'info' }, 'info', 'Robots.txt existence cannot be verified from HTML alone.', { recommendation: 'Ensure a valid `robots.txt` file is present at your domain root (e.g., `https://example.com/robots.txt`) to guide search engine crawlers and define your sitemap location.' });
+            return createResult({ id: 'technical-robots-txt-hint', name: 'Robots.txt Hint', category: 'technical', severity: 'info' }, 'info', 'Robots.txt existence cannot be verified from HTML alone.', {
+                recommendation: 'Ensure you have a valid robots.txt file at your domain root.',
+                evidence: {
+                    expected: 'A robots.txt file at /robots.txt',
+                    impact: 'robots.txt tells search engines which pages to crawl. It should also point to your sitemap.xml for efficient discovery of all pages.',
+                    example: '# Example robots.txt\nUser-agent: *\nAllow: /\nDisallow: /admin/\nDisallow: /private/\n\nSitemap: https://example.com/sitemap.xml',
+                    learnMore: 'https://developers.google.com/search/docs/crawling-indexing/robots/create-robots-txt'
+                }
+            });
         },
     },
     {
@@ -209,8 +337,9 @@ export const technicalRules = [
         severity: 'warning',
         description: 'URLs should not have more than 3 query parameters',
         check: (ctx) => {
-            if (!ctx.url)
-                return null;
+            if (!ctx.url) {
+                return createResult({ id: 'url-many-parameters', name: 'Too Many URL Parameters', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (URL data unavailable)', { recommendation: 'This rule checks for excessive URL parameters' });
+            }
             try {
                 const url = new URL(ctx.url);
                 const paramCount = Array.from(url.searchParams.keys()).length;
@@ -221,14 +350,15 @@ export const technicalRules = [
                         evidence: {
                             found: url.search,
                             expected: '3 or fewer parameters',
-                            impact: 'Multiple parameters make URLs less enticing and may cause indexing issues'
+                            impact: 'Multiple parameters make URLs less enticing to click and may cause indexing issues. Search engines may treat parameter variations as duplicate content, wasting crawl budget.',
+                            learnMore: 'https://developers.google.com/search/docs/crawling-indexing/url-structure#use-simple-urls'
                         }
                     });
                 }
             }
             catch {
             }
-            return null;
+            return createResult({ id: 'url-many-parameters', name: 'Too Many URL Parameters', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (3 or fewer URL parameters)', { recommendation: 'URL parameters are within acceptable limits' });
         },
     },
     {
@@ -238,8 +368,9 @@ export const technicalRules = [
         severity: 'error',
         description: 'Pages should not use Flash, Java Applets, or Silverlight',
         check: (ctx) => {
-            if (ctx.hasDeprecatedPlugins === undefined)
-                return null;
+            if (ctx.hasDeprecatedPlugins === undefined) {
+                return createResult({ id: 'deprecated-plugins', name: 'Deprecated Plugins', category: 'technical', severity: 'error' }, 'info', 'Not applicable (deprecated plugins data unavailable)', { recommendation: 'This rule checks for Flash, Java, and Silverlight usage' });
+            }
             if (ctx.hasDeprecatedPlugins) {
                 return createResult({ id: 'deprecated-plugins', name: 'Deprecated Plugins', category: 'technical', severity: 'error' }, 'fail', 'Page uses deprecated plugins (Flash, Java, or Silverlight)', {
                     recommendation: 'Convert plugin content to HTML5',
@@ -251,7 +382,7 @@ export const technicalRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'deprecated-plugins', name: 'Deprecated Plugins', category: 'technical', severity: 'error' }, 'info', 'Not applicable (no deprecated plugins detected)', { recommendation: 'No Flash, Java, or Silverlight plugins found' });
         },
     },
     {
@@ -261,19 +392,89 @@ export const technicalRules = [
         severity: 'error',
         description: 'Pages should not use <frame> or <frameset> tags',
         check: (ctx) => {
-            if (ctx.hasFrameTags === undefined)
-                return null;
+            if (ctx.hasFrameTags === undefined) {
+                return createResult({ id: 'frame-tags', name: 'Frame Tags', category: 'technical', severity: 'error' }, 'info', 'Not applicable (frame tags data unavailable)', { recommendation: 'This rule checks for obsolete <frame> and <frameset> tags' });
+            }
             if (ctx.hasFrameTags) {
                 return createResult({ id: 'frame-tags', name: 'Frame Tags', category: 'technical', severity: 'error' }, 'fail', 'Page uses <frame> or <frameset> tags', {
                     recommendation: 'Remove frame tags and restructure using modern HTML',
                     evidence: {
                         found: '<frame> or <frameset> tags detected',
                         expected: 'No frame tags',
-                        impact: 'Search engines have difficulty indexing content within frames, affecting rankings'
+                        impact: 'Frames are obsolete HTML. Search engines have difficulty indexing content within frames. Mobile devices don\'t support them well. Use modern CSS layouts instead.',
+                        learnMore: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame'
+                    }
+                });
+            }
+            return createResult({ id: 'frame-tags', name: 'Frame Tags', category: 'technical', severity: 'error' }, 'info', 'Not applicable (no frame tags detected)', { recommendation: 'No obsolete frame tags found' });
+        },
+    },
+    {
+        id: 'avoid-iframes',
+        name: 'Avoid iFrames',
+        category: 'technical',
+        severity: 'info',
+        description: 'iFrames can cause SEO and usability issues.',
+        check: (ctx) => {
+            if (ctx.iframeCount && ctx.iframeCount > 0) {
+                return createResult({ id: 'avoid-iframes', name: 'iFrames Usage', category: 'technical', severity: 'info' }, 'info', `${ctx.iframeCount} iFrame(s) detected`, {
+                    value: ctx.iframeCount,
+                    recommendation: 'Avoid iFrames for main content. They can be hard to index and navigate.',
+                    evidence: {
+                        found: `${ctx.iframeCount} iframes`,
+                        expected: 'Minimal iframe usage, only for embeds (videos, maps)',
+                        impact: 'Content inside iframes is treated as separate pages and may not contribute to the parent page\'s SEO. Iframes can also slow page load and cause layout shifts.',
+                        example: 'Acceptable: <iframe src="https://www.youtube.com/embed/..." loading="lazy">\nAvoid: Main content inside iframes',
+                        learnMore: 'https://developers.google.com/search/docs/crawling-indexing/mobile/mobile-sites-mobile-first-indexing#iframes'
+                    }
+                });
+            }
+            return createResult({ id: 'avoid-iframes', name: 'Avoid iFrames', category: 'technical', severity: 'info' }, 'info', 'Not applicable (no iframes detected)', { recommendation: 'No iframes found on this page' });
+        },
+    },
+    {
+        id: 'deprecated-html-tags',
+        name: 'Deprecated HTML Tags',
+        category: 'technical',
+        severity: 'warning',
+        description: 'Avoid deprecated HTML tags like <center>, <font>, <marquee>',
+        check: (ctx) => {
+            if (ctx.deprecatedTagsCount && ctx.deprecatedTagsCount > 0) {
+                return createResult({ id: 'deprecated-html-tags', name: 'Deprecated HTML Tags', category: 'technical', severity: 'warning' }, 'warn', `${ctx.deprecatedTagsCount} deprecated HTML tags found`, {
+                    value: ctx.deprecatedTagsCount,
+                    recommendation: 'Replace deprecated tags (center, font, marquee, etc.) with CSS.',
+                    evidence: {
+                        found: ctx.deprecatedTagsFound?.join(', '),
+                        expected: 'Modern HTML5 elements with CSS styling',
+                        impact: 'Deprecated tags like <center>, <font>, and <marquee> are obsolete. They indicate outdated code that may not render correctly in all browsers.',
+                        example: 'Instead of <center>text</center>, use <div style="text-align: center">text</div>\nInstead of <font color="red">, use <span style="color: red">',
+                        learnMore: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element#obsolete_and_deprecated_elements'
+                    }
+                });
+            }
+            return createResult({ id: 'deprecated-html-tags', name: 'Deprecated HTML Tags', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (no deprecated tags detected)', { recommendation: 'No obsolete HTML tags found' });
+        },
+    },
+    {
+        id: 'apple-touch-icon',
+        name: 'Apple Touch Icon',
+        category: 'technical',
+        severity: 'info',
+        description: 'Add an apple-touch-icon for iOS devices',
+        check: (ctx) => {
+            if (ctx.hasAppleTouchIcon === false) {
+                return createResult({ id: 'apple-touch-icon', name: 'Apple Touch Icon', category: 'technical', severity: 'info' }, 'info', 'Missing apple-touch-icon', {
+                    recommendation: 'Add an Apple Touch Icon for iOS devices.',
+                    evidence: {
+                        found: 'No apple-touch-icon link tag',
+                        expected: '<link rel="apple-touch-icon"> pointing to a 180x180 PNG',
+                        impact: 'Apple Touch Icons appear when users add your site to their iOS home screen. Without one, iOS will use a screenshot of your page, which often looks poor.',
+                        example: '<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">',
+                        learnMore: 'https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html'
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'apple-touch-icon', name: 'Apple Touch Icon', category: 'technical', severity: 'info' }, 'pass', 'Apple Touch Icon present');
         },
     },
 ];