recker 1.0.43 → 1.0.44

package/dist/seo/rules/crawl.js

@@ -31,8 +31,9 @@ export const crawlRules = [
         severity: 'error',
         description: 'Check if page is blocked from indexing',
         check: (ctx) => {
-            if (!ctx.metaRobots)
-                return null;
+            if (!ctx.metaRobots) {
+                return createResult({ id: 'crawl-robots-noindex', name: 'Robots Noindex', category: 'technical', severity: 'error' }, 'info', 'Not applicable (robots meta tag not present)', { recommendation: 'This rule checks for noindex directives when robots meta tags are present' });
+            }
             const hasNoindex = ctx.metaRobots.some(r => r.toLowerCase().includes('noindex'));
             if (hasNoindex) {
                 return createResult({ id: 'crawl-robots-noindex', name: 'Robots Noindex', category: 'technical', severity: 'error' }, 'fail', 'Page is set to noindex', {
@@ -43,7 +44,7 @@ export const crawlRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'crawl-robots-noindex', name: 'Robots Noindex', category: 'technical', severity: 'error' }, 'info', 'Not applicable (noindex not detected)', { recommendation: 'This rule checks for noindex directives that would prevent page indexing' });
         },
     },
     {
@@ -53,8 +54,9 @@ export const crawlRules = [
         severity: 'warning',
         description: 'Check if page links are blocked from following',
         check: (ctx) => {
-            if (!ctx.metaRobots)
-                return null;
+            if (!ctx.metaRobots) {
+                return createResult({ id: 'crawl-robots-nofollow', name: 'Robots Nofollow', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (robots meta tag not present)', { recommendation: 'This rule checks for nofollow directives when robots meta tags are present' });
+            }
             const hasNofollow = ctx.metaRobots.some(r => r.toLowerCase().includes('nofollow'));
             if (hasNofollow) {
                 return createResult({ id: 'crawl-robots-nofollow', name: 'Robots Nofollow', category: 'technical', severity: 'warning' }, 'warn', 'Page has nofollow directive', {
@@ -65,7 +67,7 @@ export const crawlRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'crawl-robots-nofollow', name: 'Robots Nofollow', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (nofollow not detected)', { recommendation: 'This rule checks for nofollow directives that would prevent link following' });
         },
     },
     {
@@ -105,12 +107,14 @@ export const crawlRules = [
         severity: 'warning',
         description: 'Check X-Robots-Tag HTTP header for indexing directives',
         check: (ctx) => {
-            if (!ctx.responseHeaders)
-                return null;
+            if (!ctx.responseHeaders) {
+                return createResult({ id: 'crawl-x-robots-tag', name: 'X-Robots-Tag Header', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (response headers unavailable)', { recommendation: 'This rule checks for X-Robots-Tag headers when HTTP response headers are available' });
+            }
             const xRobotsTag = ctx.responseHeaders['x-robots-tag'] ||
                 ctx.responseHeaders['X-Robots-Tag'];
-            if (!xRobotsTag)
-                return null;
+            if (!xRobotsTag) {
+                return createResult({ id: 'crawl-x-robots-tag', name: 'X-Robots-Tag Header', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (X-Robots-Tag header not present)', { recommendation: 'This rule checks for X-Robots-Tag headers when the header is present' });
+            }
             const tagValue = Array.isArray(xRobotsTag) ? xRobotsTag.join(', ') : xRobotsTag;
             if (tagValue.toLowerCase().includes('noindex')) {
                 return createResult({ id: 'crawl-x-robots-tag', name: 'X-Robots-Tag Header', category: 'technical', severity: 'warning' }, 'fail', 'X-Robots-Tag contains noindex', {
@@ -151,8 +155,9 @@ export const crawlRules = [
         severity: 'info',
         description: 'Canonical should point to the current page or explicit alternate',
         check: (ctx) => {
-            if (!ctx.hasCanonical || !ctx.canonicalUrl || !ctx.url)
-                return null;
+            if (!ctx.hasCanonical || !ctx.canonicalUrl || !ctx.url) {
+                return createResult({ id: 'crawl-canonical-self', name: 'Canonical Self-Reference', category: 'technical', severity: 'info' }, 'info', 'Not applicable (canonical URL or page URL unavailable)', { recommendation: 'This rule checks canonical self-reference when canonical and page URL information is available' });
+            }
             const normalizeUrl = (url) => {
                 try {
                     const u = new URL(url);
@@ -174,7 +179,7 @@ export const crawlRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'crawl-canonical-self', name: 'Canonical Self-Reference', category: 'technical', severity: 'info' }, 'info', 'Not applicable (canonical is self-referencing)', { recommendation: 'This rule checks for non-self-referencing canonicals which may indicate URL consolidation' });
         },
     },
     {
@@ -184,8 +189,9 @@ export const crawlRules = [
         severity: 'warning',
         description: 'Canonical URL should be absolute, not relative',
         check: (ctx) => {
-            if (!ctx.canonicalUrl)
-                return null;
+            if (!ctx.canonicalUrl) {
+                return createResult({ id: 'crawl-canonical-absolute', name: 'Canonical Absolute URL', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (canonical URL not present)', { recommendation: 'This rule checks canonical URL format when a canonical URL exists' });
+            }
             const isAbsolute = ctx.canonicalUrl.startsWith('http://') ||
                 ctx.canonicalUrl.startsWith('https://');
             if (!isAbsolute) {
@@ -197,7 +203,7 @@ export const crawlRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'crawl-canonical-absolute', name: 'Canonical Absolute URL', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (canonical URL is absolute)', { recommendation: 'This rule checks for relative canonical URLs which should be avoided' });
         },
     },
     {
@@ -207,8 +213,9 @@ export const crawlRules = [
         severity: 'warning',
         description: 'Canonical URL should use HTTPS',
         check: (ctx) => {
-            if (!ctx.canonicalUrl)
-                return null;
+            if (!ctx.canonicalUrl) {
+                return createResult({ id: 'crawl-canonical-https', name: 'Canonical HTTPS', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (canonical URL not present)', { recommendation: 'This rule checks canonical URL protocol when a canonical URL exists' });
+            }
             if (ctx.canonicalUrl.startsWith('http://')) {
                 return createResult({ id: 'crawl-canonical-https', name: 'Canonical HTTPS', category: 'technical', severity: 'warning' }, 'warn', 'Canonical URL uses HTTP instead of HTTPS', {
                     evidence: {
@@ -218,7 +225,7 @@ export const crawlRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'crawl-canonical-https', name: 'Canonical HTTPS', category: 'technical', severity: 'warning' }, 'info', 'Not applicable (canonical URL uses HTTPS)', { recommendation: 'This rule checks for HTTP canonical URLs which should use HTTPS instead' });
         },
     },
     {
@@ -228,8 +235,9 @@ export const crawlRules = [
         severity: 'info',
         description: 'URLs with tracking parameters should have proper canonical',
         check: (ctx) => {
-            if (!ctx.url)
-                return null;
+            if (!ctx.url) {
+                return createResult({ id: 'crawl-url-parameters', name: 'URL Parameters', category: 'technical', severity: 'info' }, 'info', 'Not applicable (page URL unavailable)', { recommendation: 'This rule checks for tracking parameters when page URL information is available' });
+            }
             try {
                 const url = new URL(ctx.url);
                 const trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'fbclid', 'gclid', 'ref'];
@@ -247,7 +255,7 @@ export const crawlRules = [
             }
             catch {
             }
-            return null;
+            return createResult({ id: 'crawl-url-parameters', name: 'URL Parameters', category: 'technical', severity: 'info' }, 'info', 'Not applicable (no tracking parameters detected or canonical is present)', { recommendation: 'This rule checks for tracking parameters without canonical tags' });
         },
     },
     {
@@ -257,8 +265,9 @@ export const crawlRules = [
         severity: 'info',
         description: 'Paginated content should use proper rel attributes',
         check: (ctx) => {
-            if (!ctx.isPaginatedPage)
-                return null;
+            if (!ctx.isPaginatedPage) {
+                return createResult({ id: 'crawl-pagination-rel', name: 'Pagination Links', category: 'technical', severity: 'info' }, 'info', 'Not applicable (page is not paginated)', { recommendation: 'This rule checks pagination links on paginated pages only' });
+            }
             const hasPrevNext = ctx.hasRelPrev || ctx.hasRelNext;
             if (!hasPrevNext) {
                 return createResult({ id: 'crawl-pagination-rel', name: 'Pagination Links', category: 'technical', severity: 'info' }, 'info', 'Paginated page missing rel="prev/next" (deprecated but still useful)', {
@@ -280,8 +289,9 @@ export const crawlRules = [
         severity: 'info',
         description: 'Check for noarchive and nocache directives',
         check: (ctx) => {
-            if (!ctx.metaRobots)
-                return null;
+            if (!ctx.metaRobots) {
+                return createResult({ id: 'crawl-noarchive', name: 'Cache Directives', category: 'technical', severity: 'info' }, 'info', 'Not applicable (robots meta tag not present)', { recommendation: 'This rule checks for cache directives when robots meta tags are present' });
+            }
             const directives = ctx.metaRobots.join(', ').toLowerCase();
             const hasNoarchive = directives.includes('noarchive');
             const hasNocache = directives.includes('nocache');
@@ -301,7 +311,7 @@ export const crawlRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'crawl-noarchive', name: 'Cache Directives', category: 'technical', severity: 'info' }, 'info', 'Not applicable (no cache restriction directives present)', { recommendation: 'This rule checks for cache restriction directives in robots meta tags' });
         },
     },
     {
@@ -311,8 +321,9 @@ export const crawlRules = [
         severity: 'info',
         description: 'Website should have a robots.txt file',
         check: (ctx) => {
-            if (ctx.robotsTxtExists === undefined)
-                return null;
+            if (ctx.robotsTxtExists === undefined) {
+                return createResult({ id: 'robots-txt-exists', name: 'robots.txt Exists', category: 'crawlability', severity: 'info' }, 'info', 'Not applicable (robots.txt status unavailable)', { recommendation: 'This rule checks for robots.txt file when robots.txt information is available' });
+            }
             if (!ctx.robotsTxtExists) {
                 return createResult({ id: 'robots-txt-exists', name: 'robots.txt Exists', category: 'crawlability', severity: 'info' }, 'info', 'No robots.txt file found', {
                     recommendation: 'Create a robots.txt file to control search engine crawling',
@@ -333,8 +344,9 @@ export const crawlRules = [
         severity: 'warning',
         description: 'robots.txt should reference sitemap.xml location',
         check: (ctx) => {
-            if (ctx.robotsTxtHasSitemap === undefined)
-                return null;
+            if (ctx.robotsTxtHasSitemap === undefined) {
+                return createResult({ id: 'sitemap-in-robots', name: 'Sitemap Reference in robots.txt', category: 'crawlability', severity: 'warning' }, 'info', 'Not applicable (robots.txt sitemap reference status unavailable)', { recommendation: 'This rule checks for sitemap references in robots.txt when robots.txt information is available' });
+            }
             if (!ctx.robotsTxtHasSitemap) {
                 return createResult({ id: 'sitemap-in-robots', name: 'Sitemap Reference in robots.txt', category: 'crawlability', severity: 'warning' }, 'warn', 'robots.txt does not reference sitemap.xml', {
                     recommendation: 'Add sitemap location to robots.txt',
@@ -355,8 +367,9 @@ export const crawlRules = [
         severity: 'warning',
         description: 'CSS/JS resources should not be blocked by robots.txt',
         check: (ctx) => {
-            if (ctx.blockedResources === undefined)
-                return null;
+            if (ctx.blockedResources === undefined) {
+                return createResult({ id: 'blocked-resources', name: 'Blocked Resources', category: 'crawlability', severity: 'warning' }, 'info', 'Not applicable (blocked resources information unavailable)', { recommendation: 'This rule checks for blocked resources when resource blocking information is available' });
+            }
             if (ctx.blockedResources > 0) {
                 return createResult({ id: 'blocked-resources', name: 'Blocked Resources', category: 'crawlability', severity: 'warning' }, 'warn', `${ctx.blockedResources} resources blocked by robots.txt`, {
                     value: ctx.blockedResources,
@@ -369,7 +382,7 @@ export const crawlRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'blocked-resources', name: 'Blocked Resources', category: 'crawlability', severity: 'warning' }, 'info', 'Not applicable (no resources blocked by robots.txt)', { recommendation: 'This rule checks for CSS/JS resources blocked by robots.txt' });
         },
     },
     {
@@ -379,8 +392,9 @@ export const crawlRules = [
         severity: 'warning',
         description: 'X-Robots-Tag should not block important pages',
         check: (ctx) => {
-            if (!ctx.xRobotsTag)
-                return null;
+            if (!ctx.xRobotsTag) {
+                return createResult({ id: 'x-robots-tag-noindex', name: 'X-Robots-Tag Noindex', category: 'crawlability', severity: 'warning' }, 'info', 'Not applicable (X-Robots-Tag header not present)', { recommendation: 'This rule checks X-Robots-Tag for noindex directives when the header is present' });
+            }
             const tag = ctx.xRobotsTag.toLowerCase();
             if (tag.includes('noindex')) {
                 return createResult({ id: 'x-robots-tag-noindex', name: 'X-Robots-Tag Noindex', category: 'crawlability', severity: 'warning' }, 'warn', 'Page blocked by X-Robots-Tag: noindex', {
@@ -392,7 +406,7 @@ export const crawlRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'x-robots-tag-noindex', name: 'X-Robots-Tag Noindex', category: 'crawlability', severity: 'warning' }, 'info', 'Not applicable (X-Robots-Tag does not contain noindex)', { recommendation: 'This rule checks for noindex in X-Robots-Tag header' });
         },
     },
     {
@@ -402,8 +416,9 @@ export const crawlRules = [
         severity: 'info',
         description: 'External resources blocked by robots.txt may affect rendering',
         check: (ctx) => {
-            if (ctx.blockedExternalResources === undefined)
-                return null;
+            if (ctx.blockedExternalResources === undefined) {
+                return createResult({ id: 'blocked-external-resources', name: 'Blocked External Resources', category: 'crawlability', severity: 'info' }, 'info', 'Not applicable (blocked external resources information unavailable)', { recommendation: 'This rule checks for blocked external resources when resource blocking information is available' });
+            }
             if (ctx.blockedExternalResources > 0) {
                 return createResult({ id: 'blocked-external-resources', name: 'Blocked External Resources', category: 'crawlability', severity: 'info' }, 'info', `${ctx.blockedExternalResources} external resources blocked by robots.txt`, {
                     value: ctx.blockedExternalResources,
@@ -414,7 +429,7 @@ export const crawlRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'blocked-external-resources', name: 'Blocked External Resources', category: 'crawlability', severity: 'info' }, 'info', 'Not applicable (no external resources blocked by robots.txt)', { recommendation: 'This rule checks for external resources blocked by robots.txt' });
         },
     },
 ];

package/dist/seo/rules/cwv.js

@@ -7,8 +7,9 @@ export const cwvRules = [
         severity: 'warning',
         description: 'Hero images should be optimized for fast LCP',
         check: (ctx) => {
-            if (!ctx.lcpCandidate)
-                return null;
+            if (!ctx.lcpCandidate) {
+                return createResult({ id: 'cwv-lcp-hero-image', name: 'LCP Hero Image', category: 'performance', severity: 'warning' }, 'info', 'No LCP candidate detected', { recommendation: 'Ensure the page has a hero image or prominent content element' });
+            }
             const issues = [];
             if (ctx.lcpCandidate.loading === 'lazy') {
                 issues.push('LCP image has loading="lazy" (should be eager or omitted)');
@@ -42,8 +43,9 @@ export const cwvRules = [
         severity: 'warning',
         description: 'Text LCP elements should render immediately without font blocking',
         check: (ctx) => {
-            if (!ctx.webFonts || ctx.webFonts.length === 0)
-                return null;
+            if (!ctx.webFonts || ctx.webFonts.length === 0) {
+                return createResult({ id: 'cwv-lcp-text-visible', name: 'LCP Text Visibility', category: 'performance', severity: 'warning' }, 'info', 'No web fonts detected', { recommendation: 'No custom web fonts to analyze' });
+            }
             const blockingFonts = ctx.webFonts.filter(f => !f.hasSwap && !f.hasOptional);
             if (blockingFonts.length > 0) {
                 return createResult({ id: 'cwv-lcp-text-visible', name: 'LCP Text Visibility', category: 'performance', severity: 'warning' }, 'warn', `${blockingFonts.length} web font(s) may block text rendering`, {
@@ -67,8 +69,9 @@ export const cwvRules = [
         severity: 'warning',
         description: 'Minimize render-blocking CSS for faster LCP',
         check: (ctx) => {
-            if (ctx.renderBlockingStylesheets === undefined)
-                return null;
+            if (ctx.renderBlockingStylesheets === undefined) {
+                return createResult({ id: 'cwv-render-blocking-css', name: 'Render-Blocking CSS', category: 'performance', severity: 'warning' }, 'info', 'Unable to check render-blocking CSS (data unavailable)', { recommendation: 'Ensure CSS resource analysis completed' });
+            }
             if (ctx.renderBlockingStylesheets > 3) {
                 return createResult({ id: 'cwv-render-blocking-css', name: 'Render-Blocking CSS', category: 'performance', severity: 'warning' }, 'warn', `${ctx.renderBlockingStylesheets} render-blocking stylesheets`, {
                     recommendation: 'Reduce render-blocking CSS or use critical CSS inline',
@@ -90,8 +93,9 @@ export const cwvRules = [
         severity: 'warning',
         description: 'Scripts in head should use async or defer',
         check: (ctx) => {
-            if (ctx.renderBlockingScripts === undefined)
-                return null;
+            if (ctx.renderBlockingScripts === undefined) {
+                return createResult({ id: 'cwv-render-blocking-js', name: 'Render-Blocking JavaScript', category: 'performance', severity: 'warning' }, 'info', 'Unable to check render-blocking scripts (data unavailable)', { recommendation: 'Ensure script analysis completed' });
+            }
             if (ctx.renderBlockingScripts > 0) {
                 return createResult({ id: 'cwv-render-blocking-js', name: 'Render-Blocking JavaScript', category: 'performance', severity: 'warning' }, 'warn', `${ctx.renderBlockingScripts} render-blocking script(s) in <head>`, {
                     recommendation: 'Add async or defer to scripts, or move to end of body',
@@ -113,8 +117,9 @@ export const cwvRules = [
         severity: 'warning',
         description: 'Images should have explicit width and height to prevent layout shift',
         check: (ctx) => {
-            if (ctx.imagesMissingDimensions === undefined)
-                return null;
+            if (ctx.imagesMissingDimensions === undefined) {
+                return createResult({ id: 'cwv-cls-image-dimensions', name: 'Image Dimensions', category: 'performance', severity: 'warning' }, 'info', 'Unable to check image dimensions (data unavailable)', { recommendation: 'Ensure image analysis completed' });
+            }
             if (ctx.imagesMissingDimensions > 0) {
                 const total = ctx.totalImages || 0;
                 const percent = total > 0 ? Math.round((ctx.imagesMissingDimensions / total) * 100) : 0;
@@ -149,7 +154,7 @@ export const cwvRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'cwv-cls-aspect-ratio', name: 'Aspect Ratio CSS', category: 'performance', severity: 'info' }, 'pass', 'Aspect ratio handling is appropriate');
         },
     },
     {
@@ -159,8 +164,9 @@ export const cwvRules = [
         severity: 'info',
         description: 'Web fonts should have size-matched fallbacks',
         check: (ctx) => {
-            if (!ctx.webFonts || ctx.webFonts.length === 0)
-                return null;
+            if (!ctx.webFonts || ctx.webFonts.length === 0) {
+                return createResult({ id: 'cwv-cls-font-fallback', name: 'Font Fallback Metrics', category: 'performance', severity: 'info' }, 'info', 'No web fonts to check', { recommendation: 'No custom web fonts detected' });
+            }
             const fontsWithoutMetrics = ctx.webFonts.filter(f => !f.hasSizeAdjust && !f.hasAscentOverride);
             if (fontsWithoutMetrics.length > 0 && ctx.webFonts.length > 0) {
                 return createResult({ id: 'cwv-cls-font-fallback', name: 'Font Fallback Metrics', category: 'performance', severity: 'info' }, 'info', 'Web fonts may cause layout shift during swap', {
@@ -177,7 +183,7 @@ export const cwvRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'cwv-cls-font-fallback', name: 'Font Fallback Metrics', category: 'performance', severity: 'info' }, 'pass', 'Font fallback metrics configured');
         },
     },
     {
@@ -236,7 +242,7 @@ export const cwvRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'cwv-critical-css', name: 'Critical CSS', category: 'performance', severity: 'info' }, 'info', 'No render-blocking stylesheets to optimize', { recommendation: 'Page has no render-blocking CSS' });
         },
     },
 ];

package/dist/seo/rules/ecommerce.js

@@ -7,10 +7,34 @@ export const ecommerceRules = [
         severity: 'warning',
         description: 'Product pages should have Product schema for rich snippets',
         check: (ctx) => {
-            if (!ctx.jsonLdTypes)
-                return null;
-            if (!ctx.isProductPage)
-                return null;
+            if (!ctx.isProductPage) {
+                return createResult({ id: 'ecommerce-product-schema', name: 'Product Schema', category: 'structured-data', severity: 'warning' }, 'info', 'Not a product page', {
+                    recommendation: 'Add Product schema if this is a product page',
+                });
+            }
+            if (!ctx.jsonLdTypes) {
+                return createResult({ id: 'ecommerce-product-schema', name: 'Product Schema', category: 'structured-data', severity: 'warning' }, 'warn', 'Product page has no JSON-LD structured data', {
+                    recommendation: 'Add Product structured data for rich snippets',
+                    evidence: {
+                        found: 'No JSON-LD structured data',
+                        expected: 'Product schema with name, image, price, availability',
+                        impact: 'Missing product schema prevents rich snippets in search results',
+                        example: `<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Product Name",
+  "image": "https://example.com/image.jpg",
+  "offers": {
+    "@type": "Offer",
+    "price": "99.99",
+    "priceCurrency": "USD"
+  }
+}
+</script>`,
+                    },
+                });
+            }
             const hasProduct = ctx.jsonLdTypes.includes('Product');
             if (!hasProduct) {
                 return createResult({ id: 'ecommerce-product-schema', name: 'Product Schema', category: 'structured-data', severity: 'warning' }, 'warn', 'Product page missing Product schema', {
@@ -42,8 +66,11 @@ export const ecommerceRules = [
         severity: 'warning',
         description: 'Product schema should include price information',
         check: (ctx) => {
-            if (!ctx.productSchema)
-                return null;
+            if (!ctx.productSchema) {
+                return createResult({ id: 'ecommerce-product-price', name: 'Product Price', category: 'structured-data', severity: 'warning' }, 'info', 'Not applicable (no Product schema)', {
+                    recommendation: 'Add Product schema first, then include price information',
+                });
+            }
             const hasPrice = ctx.productSchema.offers?.price !== undefined ||
                 ctx.productSchema.offers?.lowPrice !== undefined;
             const hasCurrency = ctx.productSchema.offers?.priceCurrency !== undefined;
@@ -51,8 +78,10 @@ export const ecommerceRules = [
                 return createResult({ id: 'ecommerce-product-price', name: 'Product Price', category: 'structured-data', severity: 'warning' }, 'warn', 'Product schema missing price', {
                     recommendation: 'Add price to Product offers for price display in search results',
                     evidence: {
+                        found: 'Product offers without price',
                         expected: 'offers.price or offers.lowPrice with priceCurrency',
                         impact: 'Products without price may not show in Google Shopping results',
+                        example: '"offers": {\n  "@type": "Offer",\n  "price": "99.99",\n  "priceCurrency": "USD"\n}',
                     },
                 });
             }
@@ -62,6 +91,8 @@ export const ecommerceRules = [
                     evidence: {
                         found: `price: ${ctx.productSchema.offers?.price}`,
                         expected: 'priceCurrency: "USD" or similar ISO 4217 code',
+                        impact: 'Currency is required for Google Shopping and price display in search results',
+                        example: '"priceCurrency": "USD"',
                     },
                 });
             }
@@ -75,8 +106,11 @@ export const ecommerceRules = [
         severity: 'info',
         description: 'Product schema should include availability status',
         check: (ctx) => {
-            if (!ctx.productSchema?.offers)
-                return null;
+            if (!ctx.productSchema?.offers) {
+                return createResult({ id: 'ecommerce-product-availability', name: 'Product Availability', category: 'structured-data', severity: 'info' }, 'info', 'Not applicable (no Product offers schema)', {
+                    recommendation: 'Add Product schema with offers to include availability',
+                });
+            }
             const availability = ctx.productSchema.offers.availability;
             if (!availability) {
                 return createResult({ id: 'ecommerce-product-availability', name: 'Product Availability', category: 'structured-data', severity: 'info' }, 'info', 'Product schema missing availability', {
@@ -99,15 +133,20 @@ export const ecommerceRules = [
         severity: 'warning',
         description: 'Product schema should include high-quality images',
         check: (ctx) => {
-            if (!ctx.productSchema)
-                return null;
+            if (!ctx.productSchema) {
+                return createResult({ id: 'ecommerce-product-image', name: 'Product Image', category: 'structured-data', severity: 'warning' }, 'info', 'Not applicable (no Product schema)', {
+                    recommendation: 'Add Product schema first, then include images',
+                });
+            }
             const hasImage = ctx.productSchema.image !== undefined;
             if (!hasImage) {
                 return createResult({ id: 'ecommerce-product-image', name: 'Product Image', category: 'structured-data', severity: 'warning' }, 'warn', 'Product schema missing image', {
                     recommendation: 'Add product images for visual search results',
                     evidence: {
+                        found: 'Product schema without image',
                         expected: 'At least one high-quality product image',
                         impact: 'Products without images are less likely to appear in image search and shopping results',
+                        example: '"image": "https://example.com/product-image.jpg"',
                     },
                 });
             }
@@ -124,8 +163,11 @@ export const ecommerceRules = [
         severity: 'info',
         description: 'Product schema can include aggregate ratings for star snippets',
         check: (ctx) => {
-            if (!ctx.productSchema)
-                return null;
+            if (!ctx.productSchema) {
+                return createResult({ id: 'ecommerce-product-reviews', name: 'Product Reviews', category: 'structured-data', severity: 'info' }, 'info', 'Not applicable (no Product schema)', {
+                    recommendation: 'Add Product schema first, then include reviews/ratings',
+                });
+            }
             const hasRating = ctx.productSchema.aggregateRating !== undefined;
             const hasReviews = ctx.productSchema.review !== undefined;
             if (!hasRating && !hasReviews) {
@@ -155,8 +197,11 @@ export const ecommerceRules = [
         severity: 'info',
         description: 'Product schema should include brand information',
         check: (ctx) => {
-            if (!ctx.productSchema)
-                return null;
+            if (!ctx.productSchema) {
+                return createResult({ id: 'ecommerce-product-brand', name: 'Product Brand', category: 'structured-data', severity: 'info' }, 'info', 'Not applicable (no Product schema)', {
+                    recommendation: 'Add Product schema first, then include brand',
+                });
+            }
             const hasBrand = ctx.productSchema.brand !== undefined;
             if (!hasBrand) {
                 return createResult({ id: 'ecommerce-product-brand', name: 'Product Brand', category: 'structured-data', severity: 'info' }, 'info', 'Product schema missing brand', {
@@ -180,8 +225,11 @@ export const ecommerceRules = [
         severity: 'info',
         description: 'Product schema should include unique identifiers (SKU, GTIN, MPN)',
         check: (ctx) => {
-            if (!ctx.productSchema)
-                return null;
+            if (!ctx.productSchema) {
+                return createResult({ id: 'ecommerce-product-sku', name: 'Product Identifiers', category: 'structured-data', severity: 'info' }, 'info', 'Not applicable (no Product schema)', {
+                    recommendation: 'Add Product schema first, then include identifiers',
+                });
+            }
             const hasSku = ctx.productSchema.sku !== undefined;
             const hasGtin = ctx.productSchema.gtin !== undefined ||
                 ctx.productSchema.gtin13 !== undefined ||
@@ -215,21 +263,25 @@ export const ecommerceRules = [
         severity: 'info',
         description: 'Time-sensitive offers should have valid date ranges',
         check: (ctx) => {
-            if (!ctx.productSchema?.offers)
-                return null;
+            if (!ctx.productSchema?.offers) {
+                return createResult({ id: 'ecommerce-offer-valid-dates', name: 'Offer Valid Dates', category: 'structured-data', severity: 'info' }, 'info', 'Not applicable (no Product offers schema)', {
+                    recommendation: 'Add Product schema with offers to enable date validation',
+                });
+            }
             const offers = ctx.productSchema.offers;
             const priceValidUntil = offers.priceValidUntil;
-            const validFrom = offers.validFrom;
             const validThrough = offers.validThrough;
             if (priceValidUntil) {
                 const endDate = new Date(priceValidUntil);
                 const now = new Date();
                 if (endDate < now) {
                     return createResult({ id: 'ecommerce-offer-valid-dates', name: 'Offer Valid Dates', category: 'structured-data', severity: 'info' }, 'warn', 'Offer priceValidUntil date has passed', {
+                        recommendation: 'Update or remove expired priceValidUntil date',
                         evidence: {
                             found: priceValidUntil,
-                            issue: 'Expired offer dates should be updated or removed',
+                            expected: 'Future date or no priceValidUntil',
                             impact: 'Expired dates may cause Google to distrust your pricing data',
+                            example: `"priceValidUntil": "${new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]}"`,
                         },
                     });
                 }
@@ -239,14 +291,22 @@ export const ecommerceRules = [
                 const now = new Date();
                 if (endDate < now) {
                     return createResult({ id: 'ecommerce-offer-valid-dates', name: 'Offer Valid Dates', category: 'structured-data', severity: 'info' }, 'warn', 'Offer validThrough date has passed', {
+                        recommendation: 'Update or remove expired validThrough date',
                         evidence: {
                             found: validThrough,
-                            issue: 'Expired validity dates should be updated',
+                            expected: 'Future date or no validThrough',
+                            impact: 'Expired validity dates may prevent offer from showing in search results',
+                            example: `"validThrough": "${new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]}"`,
                         },
                     });
                 }
             }
-            return null;
+            if (priceValidUntil || validThrough) {
+                return createResult({ id: 'ecommerce-offer-valid-dates', name: 'Offer Valid Dates', category: 'structured-data', severity: 'info' }, 'pass', 'Offer dates are valid');
+            }
+            return createResult({ id: 'ecommerce-offer-valid-dates', name: 'Offer Valid Dates', category: 'structured-data', severity: 'info' }, 'info', 'No offer date constraints specified', {
+                recommendation: 'Consider adding priceValidUntil for time-limited offers',
+            });
         },
     },
 ];