recker 1.0.43 → 1.0.44

package/dist/seo/rules/accessibility.js

@@ -7,8 +7,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: 'Buttons must have an accessible name (text content, aria-label, or title)',
         check: (ctx) => {
-            if (ctx.buttonsWithoutAriaLabel === undefined)
-                return null;
+            if (ctx.buttonsWithoutAriaLabel === undefined) {
+                return createResult({ id: 'a11y-buttons-accessible-name', name: 'Buttons Accessible Name', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no button data available)', { recommendation: 'This rule checks that all buttons have accessible names via text content, aria-label, or title attributes' });
+            }
             const count = ctx.buttonsWithoutAriaLabel;
             if (count > 0) {
                 return createResult({ id: 'a11y-buttons-accessible-name', name: 'Buttons Accessible Name', category: 'accessibility', severity: 'error' }, 'fail', `${count} button(s) do not have an accessible name`, {
@@ -32,8 +33,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: 'Image elements must have [alt] attributes',
         check: (ctx) => {
-            if (ctx.imagesWithoutAlt === undefined)
-                return null;
+            if (ctx.imagesWithoutAlt === undefined) {
+                return createResult({ id: 'a11y-images-alt', name: 'Image Alt Attributes', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no image data available)', { recommendation: 'This rule checks that all images have alt attributes for screen readers' });
+            }
             const count = ctx.imagesWithoutAlt;
             if (count > 0) {
                 return createResult({ id: 'a11y-images-alt', name: 'Image Alt Attributes', category: 'accessibility', severity: 'error' }, 'fail', `${count} image(s) do not have [alt] attributes`, {
@@ -57,8 +59,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: 'Links must have a discernible name',
         check: (ctx) => {
-            if (ctx.linksWithoutText === undefined && ctx.linksWithoutAriaLabel === undefined)
-                return null;
+            if (ctx.linksWithoutText === undefined && ctx.linksWithoutAriaLabel === undefined) {
+                return createResult({ id: 'a11y-links-discernible-name', name: 'Links Discernible Name', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no link data available)', { recommendation: 'This rule checks that all links have discernible names via text content, aria-label, or title' });
+            }
             const linksNoText = ctx.linksWithoutText ?? 0;
             const linksNoAria = ctx.linksWithoutAriaLabel ?? 0;
             const count = Math.max(linksNoText, linksNoAria);
@@ -84,8 +87,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: 'Form elements must have associated labels',
         check: (ctx) => {
-            if (ctx.inputsWithoutLabel === undefined)
-                return null;
+            if (ctx.inputsWithoutLabel === undefined) {
+                return createResult({ id: 'a11y-form-labels', name: 'Form Input Labels', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no form input data available)', { recommendation: 'This rule checks that all form inputs have associated labels for accessibility' });
+            }
             const count = ctx.inputsWithoutLabel;
             if (count > 0) {
                 return createResult({ id: 'a11y-form-labels', name: 'Form Input Labels', category: 'accessibility', severity: 'error' }, 'fail', `${count} form input(s) without associated label`, {
@@ -109,8 +113,9 @@ export const accessibilityRules = [
         severity: 'warning',
         description: 'Heading elements should be in sequentially-descending order',
         check: (ctx) => {
-            if (ctx.headingHierarchyValid === undefined)
-                return null;
+            if (ctx.headingHierarchyValid === undefined) {
+                return createResult({ id: 'a11y-heading-order', name: 'Heading Order', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no heading data available)', { recommendation: 'This rule checks that headings follow a logical order (H1 → H2 → H3) without skipping levels' });
+            }
             if (!ctx.headingHierarchyValid) {
                 return createResult({ id: 'a11y-heading-order', name: 'Heading Order', category: 'accessibility', severity: 'warning' }, 'warn', 'Heading elements are not in sequentially-descending order', {
                     recommendation: 'Ensure headings follow a logical order (H1 → H2 → H3) without skipping levels',
@@ -132,8 +137,9 @@ export const accessibilityRules = [
         severity: 'warning',
         description: 'No element should have a [tabindex] value greater than 0',
         check: (ctx) => {
-            if (ctx.elementsWithHighTabindex === undefined)
-                return null;
+            if (ctx.elementsWithHighTabindex === undefined) {
+                return createResult({ id: 'a11y-tabindex', name: 'Tabindex Values', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no tabindex data available)', { recommendation: 'This rule checks that no element has a tabindex value greater than 0, which can confuse keyboard users' });
+            }
             const count = ctx.elementsWithHighTabindex;
             if (count > 0) {
                 return createResult({ id: 'a11y-tabindex', name: 'Tabindex Values', category: 'accessibility', severity: 'warning' }, 'warn', `${count} element(s) have tabindex > 0`, {
@@ -157,8 +163,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: '[aria-*] attributes must be valid and not misspelled',
         check: (ctx) => {
-            if (ctx.invalidAriaAttributes === undefined)
-                return null;
+            if (ctx.invalidAriaAttributes === undefined) {
+                return createResult({ id: 'a11y-aria-valid-attrs', name: 'Valid ARIA Attributes', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no ARIA attribute data available)', { recommendation: 'This rule checks that all aria-* attributes are valid and not misspelled' });
+            }
             const count = ctx.invalidAriaAttributes;
             if (count > 0) {
                 return createResult({ id: 'a11y-aria-valid-attrs', name: 'Valid ARIA Attributes', category: 'accessibility', severity: 'error' }, 'fail', `${count} invalid or misspelled aria-* attribute(s) found`, {
@@ -182,8 +189,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: '[aria-*] attributes must have valid values',
         check: (ctx) => {
-            if (ctx.invalidAriaValues === undefined)
-                return null;
+            if (ctx.invalidAriaValues === undefined) {
+                return createResult({ id: 'a11y-aria-valid-values', name: 'ARIA Attribute Values', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no ARIA value data available)', { recommendation: 'This rule checks that all aria-* attributes have valid values' });
+            }
             const count = ctx.invalidAriaValues;
             if (count > 0) {
                 return createResult({ id: 'a11y-aria-valid-values', name: 'ARIA Attribute Values', category: 'accessibility', severity: 'error' }, 'fail', `${count} aria-* attribute(s) have invalid values`, {
@@ -207,8 +215,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: '[role] values must be valid',
         check: (ctx) => {
-            if (ctx.invalidAriaRoles === undefined)
-                return null;
+            if (ctx.invalidAriaRoles === undefined) {
+                return createResult({ id: 'a11y-aria-roles', name: 'Valid ARIA Roles', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no ARIA role data available)', { recommendation: 'This rule checks that all role values are valid ARIA roles' });
+            }
             const count = ctx.invalidAriaRoles;
             if (count > 0) {
                 return createResult({ id: 'a11y-aria-roles', name: 'Valid ARIA Roles', category: 'accessibility', severity: 'error' }, 'fail', `${count} invalid [role] value(s) found`, {
@@ -232,8 +241,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: '[role]s must have all required [aria-*] attributes',
         check: (ctx) => {
-            if (ctx.missingRequiredAriaAttrs === undefined)
-                return null;
+            if (ctx.missingRequiredAriaAttrs === undefined) {
+                return createResult({ id: 'a11y-aria-required-attrs', name: 'Required ARIA Attributes', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no required ARIA attribute data available)', { recommendation: 'This rule checks that elements with ARIA roles have all required aria-* attributes' });
+            }
             const count = ctx.missingRequiredAriaAttrs;
             if (count > 0) {
                 return createResult({ id: 'a11y-aria-required-attrs', name: 'Required ARIA Attributes', category: 'accessibility', severity: 'error' }, 'fail', `${count} element(s) with roles missing required aria-* attributes`, {
@@ -257,8 +267,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: '[aria-hidden="true"] must not be present on the document <body>',
         check: (ctx) => {
-            if (ctx.hasAriaHiddenBody === undefined)
-                return null;
+            if (ctx.hasAriaHiddenBody === undefined) {
+                return createResult({ id: 'a11y-aria-hidden-body', name: 'ARIA Hidden Body', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no body element data available)', { recommendation: 'This rule checks that aria-hidden is not present on the document body' });
+            }
             if (ctx.hasAriaHiddenBody) {
                 return createResult({ id: 'a11y-aria-hidden-body', name: 'ARIA Hidden Body', category: 'accessibility', severity: 'error' }, 'fail', 'aria-hidden="true" is present on document <body>', {
                     recommendation: 'Remove aria-hidden from <body> element',
@@ -280,8 +291,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: '[aria-hidden="true"] elements must not contain focusable descendants',
         check: (ctx) => {
-            if (ctx.ariaHiddenFocusableCount === undefined)
-                return null;
+            if (ctx.ariaHiddenFocusableCount === undefined) {
+                return createResult({ id: 'a11y-aria-hidden-focus', name: 'ARIA Hidden Focusable', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no aria-hidden focusable data available)', { recommendation: 'This rule checks that aria-hidden elements do not contain focusable descendants' });
+            }
             const count = ctx.ariaHiddenFocusableCount;
             if (count > 0) {
                 return createResult({ id: 'a11y-aria-hidden-focus', name: 'ARIA Hidden Focusable', category: 'accessibility', severity: 'error' }, 'fail', `${count} aria-hidden element(s) contain focusable descendants`, {
@@ -305,8 +317,9 @@ export const accessibilityRules = [
         severity: 'warning',
         description: 'Deprecated ARIA roles should not be used',
         check: (ctx) => {
-            if (ctx.deprecatedAriaRoles === undefined)
-                return null;
+            if (ctx.deprecatedAriaRoles === undefined) {
+                return createResult({ id: 'a11y-aria-deprecated', name: 'Deprecated ARIA Roles', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no deprecated ARIA role data available)', { recommendation: 'This rule checks that deprecated ARIA roles are not used' });
+            }
             const count = ctx.deprecatedAriaRoles;
             if (count > 0) {
                 return createResult({ id: 'a11y-aria-deprecated', name: 'Deprecated ARIA Roles', category: 'accessibility', severity: 'warning' }, 'warn', `${count} deprecated ARIA role(s) found`, {
@@ -330,8 +343,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: 'ARIA IDs must be unique',
         check: (ctx) => {
-            if (ctx.duplicateAriaIds === undefined)
-                return null;
+            if (ctx.duplicateAriaIds === undefined) {
+                return createResult({ id: 'a11y-aria-ids-unique', name: 'ARIA IDs Unique', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no ARIA ID data available)', { recommendation: 'This rule checks that all IDs referenced by aria-labelledby, aria-describedby, etc. are unique' });
+            }
             const count = ctx.duplicateAriaIds;
             if (count > 0) {
                 return createResult({ id: 'a11y-aria-ids-unique', name: 'ARIA IDs Unique', category: 'accessibility', severity: 'error' }, 'fail', `${count} duplicate ARIA ID(s) found`, {
@@ -355,8 +369,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: 'Elements with role="dialog" or role="alertdialog" must have accessible names',
         check: (ctx) => {
-            if (ctx.dialogsWithoutName === undefined)
-                return null;
+            if (ctx.dialogsWithoutName === undefined) {
+                return createResult({ id: 'a11y-dialog-name', name: 'Dialog Accessible Name', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no dialog data available)', { recommendation: 'This rule checks that elements with role="dialog" or role="alertdialog" have accessible names' });
+            }
             const count = ctx.dialogsWithoutName;
             if (count > 0) {
                 return createResult({ id: 'a11y-dialog-name', name: 'Dialog Accessible Name', category: 'accessibility', severity: 'error' }, 'fail', `${count} dialog(s) without accessible name`, {
@@ -380,14 +395,17 @@ export const accessibilityRules = [
         severity: 'warning',
         description: 'Document should have a main landmark',
         check: (ctx) => {
-            if (ctx.hasMain === undefined)
-                return null;
+            if (ctx.hasMain === undefined) {
+                return createResult({ id: 'a11y-main-landmark', name: 'Main Landmark', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no main landmark data available)', { recommendation: 'This rule checks that document has a <main> element or role="main" for screen reader navigation' });
+            }
             if (!ctx.hasMain) {
                 return createResult({ id: 'a11y-main-landmark', name: 'Main Landmark', category: 'accessibility', severity: 'warning' }, 'warn', 'Document does not have a <main> landmark', {
                     recommendation: 'Add a <main> element or role="main" to identify the main content area',
                     evidence: {
+                        found: 'No <main> element or role="main"',
                         expected: '<main> or role="main"',
                         impact: 'Screen reader users cannot quickly navigate to main content',
+                        example: '<main>\n  <!-- Main content here -->\n</main>',
                         learnMore: 'https://dequeuniversity.com/rules/axe/4.4/landmark-one-main',
                     },
                 });
@@ -402,8 +420,9 @@ export const accessibilityRules = [
         severity: 'info',
         description: 'Page should contain a heading, skip link, or landmark region',
         check: (ctx) => {
-            if (ctx.hasSkipLink === undefined && ctx.hasMain === undefined && ctx.h1Count === undefined)
-                return null;
+            if (ctx.hasSkipLink === undefined && ctx.hasMain === undefined && ctx.h1Count === undefined) {
+                return createResult({ id: 'a11y-skip-link', name: 'Skip Link', category: 'accessibility', severity: 'info' }, 'info', 'Not applicable (no navigation bypass data available)', { recommendation: 'This rule checks that page contains a skip link, main landmark, or heading for keyboard navigation' });
+            }
             const hasSkip = ctx.hasSkipLink ?? false;
             const hasMain = ctx.hasMain ?? false;
             const hasH1 = (ctx.h1Count ?? 0) > 0;
@@ -411,8 +430,10 @@ export const accessibilityRules = [
                 return createResult({ id: 'a11y-skip-link', name: 'Skip Link', category: 'accessibility', severity: 'info' }, 'info', 'No skip link, main landmark, or heading found', {
                     recommendation: 'Add a skip link, <main> landmark, or at least one heading for navigation',
                     evidence: {
+                        found: 'No skip link, <main>, or heading',
                         expected: 'Skip link, <main>, or heading',
                         impact: 'Keyboard users must tab through all navigation to reach content',
+                        example: '<a href="#main-content" class="skip-link">Skip to main content</a>',
                         learnMore: 'https://dequeuniversity.com/rules/axe/4.4/bypass',
                     },
                 });
@@ -427,8 +448,9 @@ export const accessibilityRules = [
         severity: 'info',
         description: 'Data tables should have caption or aria-label',
         check: (ctx) => {
-            if (ctx.tablesWithoutCaption === undefined)
-                return null;
+            if (ctx.tablesWithoutCaption === undefined) {
+                return createResult({ id: 'a11y-table-caption', name: 'Table Caption', category: 'accessibility', severity: 'info' }, 'info', 'Not applicable (no table data available)', { recommendation: 'This rule checks that data tables have captions or aria-labels for screen readers' });
+            }
             const count = ctx.tablesWithoutCaption;
             if (count > 0) {
                 return createResult({ id: 'a11y-table-caption', name: 'Table Caption', category: 'accessibility', severity: 'info' }, 'info', `${count} table(s) without caption or aria-label`, {
@@ -451,8 +473,9 @@ export const accessibilityRules = [
         severity: 'warning',
         description: '<frame> or <iframe> elements must have a title',
         check: (ctx) => {
-            if (ctx.iframesWithoutTitle === undefined)
-                return null;
+            if (ctx.iframesWithoutTitle === undefined) {
+                return createResult({ id: 'a11y-iframe-title', name: 'Iframe Title', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no iframe data available)', { recommendation: 'This rule checks that iframes have title attributes to describe their content' });
+            }
             const count = ctx.iframesWithoutTitle;
             if (count > 0) {
                 return createResult({ id: 'a11y-iframe-title', name: 'Iframe Title', category: 'accessibility', severity: 'warning' }, 'warn', `${count} iframe(s) without title attribute`, {
@@ -476,8 +499,9 @@ export const accessibilityRules = [
         severity: 'warning',
         description: 'SVGs should have <title> or aria-label for accessibility',
         check: (ctx) => {
-            if (ctx.svgsWithoutTitle === undefined)
-                return null;
+            if (ctx.svgsWithoutTitle === undefined) {
+                return createResult({ id: 'a11y-svg-title', name: 'SVG Title', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no SVG data available)', { recommendation: 'This rule checks that SVGs have <title> elements or aria-label for accessibility' });
+            }
             const count = ctx.svgsWithoutTitle;
             if (count > 0) {
                 return createResult({ id: 'a11y-svg-title', name: 'SVG Title', category: 'accessibility', severity: 'warning' }, 'warn', `${count} SVG(s) without accessible title`, {
@@ -487,6 +511,7 @@ export const accessibilityRules = [
                         found: count,
                         expected: 0,
                         impact: 'Screen readers cannot describe SVG content',
+                        example: '<svg aria-label="Descriptive label">\n  <title>Icon description</title>\n  <!-- SVG content -->\n</svg>',
                     },
                 });
             }
@@ -500,8 +525,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: '[user-scalable="no"] should not be used and maximum-scale should not be less than 5',
         check: (ctx) => {
-            if (ctx.viewportContent === undefined)
-                return null;
+            if (ctx.viewportContent === undefined) {
+                return createResult({ id: 'a11y-viewport-zoom', name: 'Viewport Zoom', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no viewport meta tag data available)', { recommendation: 'This rule checks that viewport meta tag allows zooming for users with low vision' });
+            }
             const viewport = ctx.viewportContent.toLowerCase();
             const hasUserScalableNo = viewport.includes('user-scalable=no') || viewport.includes('user-scalable=0');
             const maxScaleMatch = viewport.match(/maximum-scale\s*=\s*([\d.]+)/);
@@ -527,14 +553,17 @@ export const accessibilityRules = [
         severity: 'error',
         description: 'Document must have a <title> element',
         check: (ctx) => {
-            if (ctx.title === undefined)
-                return null;
+            if (ctx.title === undefined) {
+                return createResult({ id: 'a11y-document-title', name: 'Document Title', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no title data available)', { recommendation: 'This rule checks that document has a <title> element for screen readers' });
+            }
             if (!ctx.title || ctx.title.trim().length === 0) {
                 return createResult({ id: 'a11y-document-title', name: 'Document Title', category: 'accessibility', severity: 'error' }, 'fail', 'Document does not have a <title> element', {
                     recommendation: 'Add a descriptive <title> element to the document',
                     evidence: {
+                        found: ctx.title || 'Empty or missing <title>',
                         expected: '<title>Page Title</title>',
                         impact: 'Screen reader users cannot identify the page',
+                        example: '<head>\n  <title>My Page - Site Name</title>\n</head>',
                         learnMore: 'https://dequeuniversity.com/rules/axe/4.4/document-title',
                     },
                 });
@@ -549,14 +578,17 @@ export const accessibilityRules = [
         severity: 'error',
         description: '<html> element must have a [lang] attribute',
         check: (ctx) => {
-            if (ctx.hasLang === undefined)
-                return null;
+            if (ctx.hasLang === undefined) {
+                return createResult({ id: 'a11y-html-lang', name: 'HTML Lang Attribute', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no HTML lang attribute data available)', { recommendation: 'This rule checks that HTML element has a lang attribute for screen readers' });
+            }
             if (!ctx.hasLang) {
                 return createResult({ id: 'a11y-html-lang', name: 'HTML Lang Attribute', category: 'accessibility', severity: 'error' }, 'fail', '<html> element does not have a [lang] attribute', {
                     recommendation: 'Add lang attribute to html element (e.g., <html lang="en">)',
                     evidence: {
+                        found: '<html> without lang attribute',
                         expected: '<html lang="en">',
                         impact: 'Screen readers may pronounce content incorrectly',
+                        example: '<html lang="en">\n  <!-- page content -->\n</html>',
                         learnMore: 'https://dequeuniversity.com/rules/axe/4.4/html-has-lang',
                     },
                 });
@@ -571,8 +603,9 @@ export const accessibilityRules = [
         severity: 'error',
         description: '<html> element must have a valid value for its [lang] attribute',
         check: (ctx) => {
-            if (!ctx.hasLang || !ctx.langValue)
-                return null;
+            if (!ctx.hasLang || !ctx.langValue) {
+                return createResult({ id: 'a11y-html-lang-valid', name: 'Valid Lang Attribute', category: 'accessibility', severity: 'error' }, 'info', 'Not applicable (no lang attribute present to validate)', { recommendation: 'This rule checks that HTML lang attribute has a valid BCP 47 language tag' });
+            }
             const validLangPattern = /^[a-z]{2,3}(-[A-Za-z]{2,4})?(-[A-Za-z0-9]{2,})?$/i;
             if (!validLangPattern.test(ctx.langValue)) {
                 return createResult({ id: 'a11y-html-lang-valid', name: 'Valid Lang Attribute', category: 'accessibility', severity: 'error' }, 'fail', `Invalid lang attribute value: ${ctx.langValue}`, {
@@ -581,6 +614,8 @@ export const accessibilityRules = [
                     evidence: {
                         found: ctx.langValue,
                         expected: 'Valid BCP 47 language tag',
+                        impact: 'Invalid language tags prevent screen readers from selecting correct voice/pronunciation',
+                        example: '<html lang="en"> or <html lang="pt-BR">',
                         learnMore: 'https://dequeuniversity.com/rules/axe/4.4/html-lang-valid',
                     },
                 });
@@ -595,8 +630,9 @@ export const accessibilityRules = [
         severity: 'warning',
         description: '<video> elements should contain a <track> element with [kind="captions"]',
         check: (ctx) => {
-            if (ctx.videoCount === undefined || ctx.videosWithCaptions === undefined)
-                return null;
+            if (ctx.videoCount === undefined || ctx.videosWithCaptions === undefined) {
+                return createResult({ id: 'a11y-video-captions', name: 'Video Captions', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no video data available)', { recommendation: 'This rule checks that video elements have caption tracks for deaf users' });
+            }
             const videos = ctx.videoCount;
             const withCaptions = ctx.videosWithCaptions;
             if (videos > 0 && withCaptions < videos) {
@@ -614,7 +650,7 @@ export const accessibilityRules = [
             if (videos > 0) {
                 return createResult({ id: 'a11y-video-captions', name: 'Video Captions', category: 'accessibility', severity: 'warning' }, 'pass', `All ${videos} video(s) have captions`);
             }
-            return null;
+            return createResult({ id: 'a11y-video-captions', name: 'Video Captions', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no video elements detected)', { recommendation: 'This rule checks that video elements have caption tracks for deaf users' });
         },
     },
     {
@@ -624,8 +660,9 @@ export const accessibilityRules = [
         severity: 'warning',
         description: 'Lists must contain only <li> elements and script supporting elements',
         check: (ctx) => {
-            if (ctx.invalidListStructure === undefined)
-                return null;
+            if (ctx.invalidListStructure === undefined) {
+                return createResult({ id: 'a11y-list-structure', name: 'List Structure', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no list structure data available)', { recommendation: 'This rule checks that lists only contain valid children (li, script, template)' });
+            }
             const count = ctx.invalidListStructure;
             if (count > 0) {
                 return createResult({ id: 'a11y-list-structure', name: 'List Structure', category: 'accessibility', severity: 'warning' }, 'warn', `${count} list(s) have invalid structure`, {
@@ -649,8 +686,9 @@ export const accessibilityRules = [
         severity: 'warning',
         description: 'All heading elements must contain content',
         check: (ctx) => {
-            if (ctx.emptyHeadings === undefined)
-                return null;
+            if (ctx.emptyHeadings === undefined) {
+                return createResult({ id: 'a11y-headings-content', name: 'Heading Content', category: 'accessibility', severity: 'warning' }, 'info', 'Not applicable (no heading content data available)', { recommendation: 'This rule checks that all heading elements contain text content' });
+            }
             const count = ctx.emptyHeadings;
             if (count > 0) {
                 return createResult({ id: 'a11y-headings-content', name: 'Heading Content', category: 'accessibility', severity: 'warning' }, 'warn', `${count} empty heading element(s) found`, {
@@ -674,8 +712,9 @@ export const accessibilityRules = [
         severity: 'info',
         description: 'Image alt attributes should not be redundant',
         check: (ctx) => {
-            if (ctx.imagesWithRedundantAlt === undefined)
-                return null;
+            if (ctx.imagesWithRedundantAlt === undefined) {
+                return createResult({ id: 'a11y-images-redundant-alt', name: 'Redundant Alt Text', category: 'accessibility', severity: 'info' }, 'info', 'Not applicable (no image alt text data available)', { recommendation: 'This rule checks that image alt text does not contain redundant phrases like "image of" or "picture of"' });
+            }
             const count = ctx.imagesWithRedundantAlt;
             if (count > 0) {
                 return createResult({ id: 'a11y-images-redundant-alt', name: 'Redundant Alt Text', category: 'accessibility', severity: 'info' }, 'info', `${count} image(s) have redundant alt text (e.g., "image of", "picture of")`, {

package/dist/seo/rules/ai-search.js

@@ -7,8 +7,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'llms.txt helps AI systems understand your site (llmstxt.org)',
         check: (ctx) => {
-            if (ctx.llmsTxt === undefined)
-                return null;
+            if (ctx.llmsTxt === undefined) {
+                return createResult({ id: 'ai-llms-txt-exists', name: 'llms.txt File', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (llms.txt data unavailable)', { recommendation: 'This rule checks for llms.txt file to optimize for AI/LLM discovery' });
+            }
             if (!ctx.llmsTxt.exists) {
                 return createResult({ id: 'ai-llms-txt-exists', name: 'llms.txt File', category: 'ai-search', severity: 'info' }, 'info', 'llms.txt not found', {
                     recommendation: 'Create llms.txt to optimize for AI/LLM discovery',
@@ -37,8 +38,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'llms.txt should have proper structure with site name and description',
         check: (ctx) => {
-            if (!ctx.llmsTxt?.exists || !ctx.llmsTxt.parseResult)
-                return null;
+            if (!ctx.llmsTxt?.exists || !ctx.llmsTxt.parseResult) {
+                return createResult({ id: 'ai-llms-txt-structure', name: 'llms.txt Structure', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (llms.txt does not exist or parse data unavailable)', { recommendation: 'This rule validates llms.txt structure for AI comprehension' });
+            }
             const { siteName, siteDescription, sections, links } = ctx.llmsTxt.parseResult;
             const issues = [];
             if (!siteName) {
@@ -73,8 +75,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'Content should be well-structured for AI comprehension',
         check: (ctx) => {
-            if (!ctx.headings?.structure)
-                return null;
+            if (!ctx.headings?.structure) {
+                return createResult({ id: 'ai-content-structure', name: 'AI-Friendly Content Structure', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (heading structure data unavailable)', { recommendation: 'This rule checks for well-structured content for AI comprehension' });
+            }
             const issues = [];
             const h1Count = ctx.headings.h1Count || 0;
             const hasH2 = ctx.headings.structure.some((h) => h.level === 2);
@@ -105,8 +108,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'Question headings help with AI search featured snippets',
         check: (ctx) => {
-            if (!ctx.headings?.structure)
-                return null;
+            if (!ctx.headings?.structure) {
+                return createResult({ id: 'ai-question-headings', name: 'Question-Based Headings', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (heading structure data unavailable)', { recommendation: 'This rule checks for question-based headings that trigger featured snippets' });
+            }
             const questionPatterns = [
                 /^what\s/i, /^how\s/i, /^why\s/i, /^when\s/i,
                 /^where\s/i, /^who\s/i, /^which\s/i, /^can\s/i,
@@ -130,7 +134,7 @@ export const aiSearchRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'ai-question-headings', name: 'Question-Based Headings', category: 'ai-search', severity: 'info' }, 'pass', 'Content length does not require question headings');
         },
     },
     {
@@ -140,8 +144,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'Schema.org structured data helps AI understand content',
         check: (ctx) => {
-            if (!ctx.jsonLdTypes)
-                return null;
+            if (!ctx.jsonLdTypes) {
+                return createResult({ id: 'ai-structured-data', name: 'Structured Data for AI', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (structured data unavailable)', { recommendation: 'This rule checks for Schema.org structured data for AI comprehension' });
+            }
             const aiHelpfulTypes = [
                 'Article', 'BlogPosting', 'NewsArticle', 'TechArticle',
                 'FAQPage', 'HowTo', 'QAPage',
@@ -184,8 +189,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'FAQPage schema is highly valuable for AI search results',
         check: (ctx) => {
-            if (!ctx.jsonLdTypes)
-                return null;
+            if (!ctx.jsonLdTypes) {
+                return createResult({ id: 'ai-faq-schema', name: 'FAQ Schema for AI', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (structured data unavailable)', { recommendation: 'This rule checks for FAQ/HowTo schema for AI search rich results' });
+            }
             const hasFaqSchema = ctx.jsonLdTypes.some((t) => t.includes('FAQPage'));
             const hasHowToSchema = ctx.jsonLdTypes.some((t) => t.includes('HowTo'));
             const hasQASchema = ctx.jsonLdTypes.some((t) => t.includes('QAPage'));
@@ -214,7 +220,7 @@ export const aiSearchRules = [
                     },
                 });
             }
-            return null;
+            return createResult({ id: 'ai-faq-schema', name: 'FAQ Schema for AI', category: 'ai-search', severity: 'info' }, 'pass', 'No Q&A structure detected requiring FAQ schema');
         },
     },
     {
@@ -224,8 +230,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'AI systems prefer comprehensive, in-depth content',
         check: (ctx) => {
-            if (ctx.wordCount === undefined)
-                return null;
+            if (ctx.wordCount === undefined) {
+                return createResult({ id: 'ai-content-depth', name: 'Content Depth for AI', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (word count data unavailable)', { recommendation: 'This rule checks content depth for AI search visibility' });
+            }
             const minWords = 300;
             const goodWords = 1000;
             const excellentWords = 2000;
@@ -259,8 +266,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'AI systems value fresh, updated content',
         check: (ctx) => {
-            if (!ctx.jsonLdTypes)
-                return null;
+            if (!ctx.jsonLdTypes) {
+                return createResult({ id: 'ai-content-freshness', name: 'Content Freshness Signals', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (structured data unavailable)', { recommendation: 'This rule checks for content freshness signals in structured data' });
+            }
             const hasDateSignals = ctx.jsonLdTypes.some((t) => t.includes('Article') || t.includes('BlogPosting') || t.includes('NewsArticle'));
             if (hasDateSignals) {
                 return createResult({ id: 'ai-content-freshness', name: 'Content Freshness Signals', category: 'ai-search', severity: 'info' }, 'pass', 'Article schema with date signals found');
@@ -281,8 +289,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'Check if GPTBot (OpenAI) is allowed or blocked',
         check: (ctx) => {
-            if (!ctx.robotsTxt?.parseResult)
-                return null;
+            if (!ctx.robotsTxt?.parseResult) {
+                return createResult({ id: 'ai-robots-gpt-bot', name: 'GPTBot Access', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (robots.txt data unavailable)', { recommendation: 'This rule checks if GPTBot is allowed to crawl for ChatGPT training' });
+            }
             const { userAgentBlocks } = ctx.robotsTxt.parseResult;
             const gptBotBlock = userAgentBlocks.find((b) => b.userAgents.some(ua => ua.toLowerCase().includes('gptbot')));
             if (gptBotBlock) {
@@ -307,8 +316,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'Check if Anthropic/Claude crawlers are allowed or blocked',
         check: (ctx) => {
-            if (!ctx.robotsTxt?.parseResult)
-                return null;
+            if (!ctx.robotsTxt?.parseResult) {
+                return createResult({ id: 'ai-robots-anthropic', name: 'Anthropic Claude Access', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (robots.txt data unavailable)', { recommendation: 'This rule checks if Anthropic/Claude crawlers are allowed' });
+            }
             const { userAgentBlocks } = ctx.robotsTxt.parseResult;
             const anthropicBlock = userAgentBlocks.find((b) => b.userAgents.some(ua => ua.toLowerCase().includes('anthropic') ||
                 ua.toLowerCase().includes('claude')));
@@ -323,7 +333,7 @@ export const aiSearchRules = [
                     });
                 }
             }
-            return null;
+            return createResult({ id: 'ai-robots-anthropic', name: 'Anthropic Claude Access', category: 'ai-search', severity: 'info' }, 'pass', 'Anthropic/Claude crawler is allowed (default)');
         },
     },
     {
@@ -333,8 +343,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'Content updated recently may perform better in AI search',
         check: (ctx) => {
-            if (!ctx.lastModified)
-                return null;
+            if (!ctx.lastModified) {
+                return createResult({ id: 'ai-content-last-modified', name: 'Content Last Modified', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (Last-Modified header unavailable)', { recommendation: 'This rule checks content freshness via Last-Modified header' });
+            }
             const lastModifiedDate = new Date(ctx.lastModified);
             const sixMonthsAgo = new Date();
             sixMonthsAgo.setMonth(sixMonthsAgo.getMonth() - 6);
@@ -350,7 +361,7 @@ export const aiSearchRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'ai-content-last-modified', name: 'Content Last Modified', category: 'ai-search', severity: 'info' }, 'pass', 'Content has been updated recently');
         },
     },
     {
@@ -360,8 +371,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'Very long pages may be truncated by AI search engines',
         check: (ctx) => {
-            if (ctx.wordCount === undefined)
-                return null;
+            if (ctx.wordCount === undefined) {
+                return createResult({ id: 'ai-page-too-long', name: 'Page Too Long for AI', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (word count data unavailable)', { recommendation: 'This rule checks if page length may be too long for AI processing' });
+            }
             if (ctx.wordCount > 10000) {
                 return createResult({ id: 'ai-page-too-long', name: 'Page Too Long for AI', category: 'ai-search', severity: 'info' }, 'info', `Page has ${ctx.wordCount.toLocaleString()} words (very long)`, {
                     value: ctx.wordCount,
@@ -383,7 +395,7 @@ export const aiSearchRules = [
                     }
                 });
             }
-            return null;
+            return createResult({ id: 'ai-page-too-long', name: 'Page Too Long for AI', category: 'ai-search', severity: 'info' }, 'pass', `Page length is optimal for AI processing (${ctx.wordCount.toLocaleString()} words)`);
         },
     },
     {
@@ -393,8 +405,9 @@ export const aiSearchRules = [
         severity: 'info',
         description: 'Pages should use semantic HTML for better AI understanding',
         check: (ctx) => {
-            if (ctx.semanticHtmlRatio === undefined)
-                return null;
+            if (ctx.semanticHtmlRatio === undefined) {
+                return createResult({ id: 'semantic-html-ratio', name: 'Semantic HTML Ratio', category: 'ai-search', severity: 'info' }, 'info', 'Not applicable (semantic HTML data unavailable)', { recommendation: 'This rule checks for semantic HTML usage for better AI understanding' });
+            }
             if (ctx.semanticHtmlRatio < 0.1) {
                 return createResult({ id: 'semantic-html-ratio', name: 'Semantic HTML Ratio', category: 'ai-search', severity: 'info' }, 'warn', `Low semantic HTML usage (${(ctx.semanticHtmlRatio * 100).toFixed(1)}%)`, {
                     value: ctx.semanticHtmlRatio,

package/dist/seo/rules/analytics.d.ts

@@ -0,0 +1,2 @@
+import { SeoRule } from './types.js';
+export declare const analyticsRules: SeoRule[];