semantica11y 1.0.0

package/src/engine/rules/README.md

@@ -0,0 +1,232 @@
+# Rule Reference
+
+This folder contains the default rule implementations used by `RuleEngine`.
+Each file exports one rule object. Some exported rules perform several related
+checks; those are called out under the rule file.
+
+Default rule order is defined in `../definitions.js`.
+
+## `aria-landmarks.js`
+
+Exports: `ariaLandmarksRule`
+Rule id: `aria-landmarks`
+Severity: `warning`
+
+Checks `div` elements with ARIA landmark roles that should usually be native
+landmark elements.
+
+Covered roles:
+- `role="banner"` suggests `<header>`
+- `role="contentinfo"` suggests `<footer>`
+- `role="navigation"` suggests `<nav>`
+- `role="main"` suggests `<main>`
+- `role="complementary"` suggests `<aside>`
+- `role="article"` suggests `<article>`
+- `role="region"` suggests `<section>`
+
+## `missing-form-labels.js`
+
+Exports: `missingFormLabelsRule`
+Rule id: `missing-form-labels`
+Severity: `error`
+
+Checks `input`, `textarea`, and `select` elements for an accessible label.
+
+Passes when:
+- The control is a hidden input.
+- The control has an `id` matched by `label[for]`.
+- The control is wrapped by a `label` element.
+- The control has `aria-label`.
+- The control has `aria-labelledby`.
+
+Fails when a visible form control has none of those label sources.
+
+## `heading-hierarchy.js`
+
+Exports: `headingHierarchyRule`
+Rule id: `heading-hierarchy`
+Severity: `warning`
+
+Checks document heading structure.
+
+Individual checks:
+- Missing page `<h1>`: warns when the document has no `h1`.
+- Skipped heading levels: warns when a heading jumps by more than one level
+  after a previous heading, such as `<h1>` followed by `<h3>`.
+
+## `aria-actions.js`
+
+Exports: `ariaActionsRule`
+Rule id: `aria-actions`
+Severity: `warning`
+
+Checks elements with ARIA action roles that should use native interactive
+elements when possible.
+
+Covered roles:
+- `role="button"` suggests `<button>`
+- `role="checkbox"` suggests `<input type="checkbox">`
+- `role="link"` suggests `<a>`
+- `role="textbox"` suggests `<input>` or `<textarea>`
+
+Individual checks:
+- Non-native action role usage: warns when a non-semantic element uses one of
+  the covered action roles.
+- Mismatched native action role: warns when a native interactive element has a
+  conflicting ARIA action role, such as an anchor with `role="button"`.
+
+Passes when the element already matches the native semantic element for that
+role.
+
+## `aria-expanded.js`
+
+Exports: `ariaExpandedRule`
+Rule id: `aria-expanded`
+Severity: `warning`
+
+Checks elements with `aria-expanded="true"` or `aria-expanded="false"`.
+
+Individual checks:
+- Expanded disclosure state: warns when an element uses `aria-expanded="true"`.
+- Collapsed disclosure state: warns when an element uses `aria-expanded="false"`.
+
+The suggestion is to use native `<details>` and `<summary>` elements for
+expandable content.
+
+## `aria-modal.js`
+
+Exports: `ariaModalRule`
+Rule id: `aria-modal`
+
+Checks modal dialog patterns.
+
+Individual checks:
+- ARIA modal usage: reports a `warning` when an element has `aria-modal`.
+- ARIA dialog role usage: reports a `warning` when an element has `role="dialog"`.
+- Dialog tabindex usage: reports an `error` when a `<dialog>` element has
+  `tabindex`.
+
+The suggestion is to use native `<dialog>` for modal dialogs and remove
+`tabindex` from `<dialog>`. MDN documents that `tabindex` must not be used on
+the `<dialog>` element.
+
+## `aria-structure.js`
+
+Exports: `ariaStructureRule`
+Rule id: `aria-structure`
+Severity: `warning`
+
+Checks elements with ARIA structure roles that should use native semantic
+elements when possible.
+
+Role mappings live in `../aria-structure-role-mappings.js`.
+
+Covered roles:
+- `role="article"` suggests `<article>`
+- `role="blockquote"` suggests `<blockquote>`
+- `role="caption"` suggests `<caption>`
+- `role="cell"` suggests `<td>`
+- `role="code"` suggests `<code>`
+- `role="columnheader"` suggests `<th scope="col">`
+- `role="definition"` suggests `<dfn>`
+- `role="deletion"` suggests `<del>`
+- `role="emphasis"` suggests `<em>`
+- `role="figure"` suggests `<figure>`
+- `role="generic"` suggests a more specific semantic element or removing `role="generic"`
+- `role="heading"` suggests `<h1>` through `<h6>`
+- `role="list"` suggests `<ul>` or `<ol>`
+- `role="listitem"` suggests `<li>`
+- `role="paragraph"` suggests `<p>`
+- `role="row"` suggests `<tr>`
+- `role="rowgroup"` suggests `<thead>`, `<tbody>`, or `<tfoot>`
+- `role="rowheader"` suggests `<th scope="row">`
+- `role="separator"` suggests `<hr>`
+- `role="strong"` suggests `<strong>`
+- `role="subscript"` suggests `<sub>`
+- `role="superscript"` suggests `<sup>`
+- `role="table"` suggests `<table>`
+- `role="term"` suggests `<dt>`
+- `role="time"` suggests `<time>`
+
+Passes when the element already matches the native semantic element for that
+role. `generic` always reports because there is no more specific native match.
+
+## `missing-role-action.js`
+
+Exports: `missingRoleActionRule`
+Rule id: `missing-role-action`
+Severity: `warning`
+
+Checks non-semantic elements that appear interactive but do not have native
+interactive semantics or an action role.
+
+Individual checks:
+- Focusable custom action: warns for elements with `tabindex="0"` that are not
+  native interactive elements and do not have an action role.
+- Click-only custom action: warns for elements with `onclick` that are not
+  native interactive elements and do not have an action role.
+
+Recognized action roles are `button`, `checkbox`, `link`, and `textbox`.
+
+Native interactive elements pass, including `button`, `select`, `textarea`,
+anchors with `href`, and non-hidden inputs.
+
+## `image-alt.js`
+
+Exports: `imageAltRule`
+Rule id: `image-alt`
+
+Checks `img` elements for `alt` usage and conflicting ARIA labels.
+
+Individual checks:
+- Missing `alt`: reports an `error` when an image has no `alt` attribute.
+- `aria-label` without `alt`: reports a `warning`.
+- `aria-label` with `alt=""`: reports a `warning`.
+- `aria-label` overriding `alt`: reports a `warning` when normalized
+  `aria-label` text differs from normalized `alt` text.
+
+Passes when an image has `alt` and no conflicting `aria-label`, or when
+`aria-label` exactly matches the `alt` text.
+
+## `native-label.js`
+
+Exports: `nativeLabelRule`
+Rule id: `native-label`
+
+Checks native action and form elements with `aria-label` against their native
+or visible label text.
+
+Scanned elements:
+- `button[aria-label]`
+- `a[href][aria-label]`
+- `input[aria-label]`
+- `textarea[aria-label]`
+- `select[aria-label]`
+
+Individual checks:
+- Duplicate label: reports a `warning` when `aria-label` duplicates the native
+  label text.
+- Conflicting label: reports an `error` when `aria-label` does not match the
+  native label text.
+
+Allowed cases:
+- Elements with no native label text.
+- `aria-label` values that include the native text.
+- Approved helper text added after the native text, currently
+  "opens in a new window" and "opens in new window".
+
+## `missing-key-landmark.js`
+
+Exports: `missingKeyLandmarkRule`
+Rule id: `missing-key-landmark`
+Severity: `suggestion`
+
+Checks whether the page has core structure landmarks and a heading.
+
+Individual checks:
+- Missing header landmark: passes with `<header>` or `role="banner"`.
+- Missing main content landmark: passes with `<main>` or `role="main"`.
+- Missing footer landmark: passes with `<footer>` or `role="contentinfo"`.
+- Missing page heading: passes with any `h1` through `h6`, or `role="heading"`.
+
+This rule intentionally reports suggestions rather than errors or warnings.

package/src/engine/rules/aria-actions.js

@@ -0,0 +1,109 @@
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+const ARIA_ACTION_ROLE_MAPPINGS = [
+  {
+    role: 'button',
+    semanticElement: '<button>',
+    isSemanticMatch: (element) => element.tagName.toLowerCase() === 'button',
+  },
+  {
+    role: 'checkbox',
+    semanticElement: '<input type="checkbox">',
+    isSemanticMatch: (element) =>
+      element.tagName.toLowerCase() === 'input' &&
+      element.getAttribute('type')?.toLowerCase() === 'checkbox',
+  },
+  {
+    role: 'link',
+    semanticElement: '<a>',
+    isSemanticMatch: (element) => element.tagName.toLowerCase() === 'a',
+  },
+  {
+    role: 'textbox',
+    semanticElement: '<input> or <textarea>',
+    isSemanticMatch: (element) => {
+      const tagName = element.tagName.toLowerCase();
+      const type = element.getAttribute('type')?.toLowerCase() || 'text';
+
+      return tagName === 'textarea' || (tagName === 'input' && type === 'text');
+    },
+  },
+];
+
+function getNativeActionRole(element) {
+  const tagName = element.tagName.toLowerCase();
+
+  if (tagName === 'button') {
+    return 'button';
+  }
+
+  if (tagName === 'a' && element.hasAttribute('href')) {
+    return 'link';
+  }
+
+  if (tagName === 'textarea') {
+    return 'textbox';
+  }
+
+  if (tagName === 'input') {
+    const type = element.getAttribute('type')?.toLowerCase() || 'text';
+
+    if (type === 'checkbox') {
+      return 'checkbox';
+    }
+
+    if (['button', 'reset', 'submit'].includes(type)) {
+      return 'button';
+    }
+
+    if (!['hidden', 'radio'].includes(type)) {
+      return 'textbox';
+    }
+  }
+
+  return null;
+}
+
+export const ariaActionsRule = {
+  id: 'aria-actions',
+  name: 'ARIA action usage',
+  enabled: true,
+  description: 'Detects elements using ARIA action roles that should use semantic elements',
+  check(document) {
+    const issues = [];
+
+    document.querySelectorAll('[role]').forEach((element) => {
+      const roles = element
+        .getAttribute('role')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+
+      const nativeActionRole = getNativeActionRole(element);
+
+      ARIA_ACTION_ROLE_MAPPINGS.forEach(({ role, semanticElement, isSemanticMatch }) => {
+        if (!roles.includes(role) || isSemanticMatch(element)) {
+          return;
+        }
+
+        const hasMismatchedNativeRole =
+          nativeActionRole && nativeActionRole !== role;
+
+        issues.push({
+          severity: 'warning',
+          rule: 'aria-actions',
+          element: getElementSignature(element),
+          message: hasMismatchedNativeRole
+            ? `Native ${nativeActionRole} element has mismatched ARIA ${role} role`
+            : `Element uses ARIA ${role} role instead of a semantic element`,
+          suggestion: hasMismatchedNativeRole
+            ? `Remove role="${role}" or use ${semanticElement} if the element should behave as ${role}`
+            : `Consider using ${semanticElement} element instead`,
+          line: getLineNumber(element),
+        });
+      });
+    });
+
+    return issues;
+  },
+};

package/src/engine/rules/aria-expanded.js

@@ -0,0 +1,32 @@
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+const EXPANDED_VALUES = ['true', 'false'];
+
+export const ariaExpandedRule = {
+  id: 'aria-expanded',
+  name: 'ARIA expanded disclosure',
+  enabled: true,
+  description: 'Detects aria-expanded usage that could use native disclosure elements',
+  check(document) {
+    const issues = [];
+
+    document.querySelectorAll('[aria-expanded]').forEach((element) => {
+      const value = element.getAttribute('aria-expanded')?.toLowerCase();
+
+      if (!EXPANDED_VALUES.includes(value)) {
+        return;
+      }
+
+      issues.push({
+        severity: 'warning',
+        rule: 'aria-expanded',
+        element: getElementSignature(element),
+        message: `Element uses aria-expanded="${value}" for disclosure state`,
+        suggestion: 'Consider using native <details> and <summary> elements for expandable content',
+        line: getLineNumber(element),
+      });
+    });
+
+    return issues;
+  },
+};

package/src/engine/rules/aria-landmarks.js

@@ -0,0 +1,36 @@
+import { SEMANTIC_ROLE_MAPPINGS } from '../semantic-role-mappings.js';
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+export const ariaLandmarksRule = {
+  id: 'aria-landmarks',
+  name: 'ARIA landmark usage',
+  enabled: true,
+  description: 'Detects elements using ARIA landmark roles that should use semantic elements',
+  check(document) {
+    const issues = [];
+
+    document.querySelectorAll('div').forEach((div) => {
+      const roles = (div.getAttribute('role') || '')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+
+      SEMANTIC_ROLE_MAPPINGS.forEach(({ element, ariaRole, message }) => {
+        if (!roles.includes(ariaRole)) {
+          return;
+        }
+
+        issues.push({
+          severity: 'warning',
+          rule: 'aria-landmarks',
+          element: getElementSignature(div),
+          message,
+          suggestion: `Consider using <${element}> semantic element instead`,
+          line: getLineNumber(div),
+        });
+      });
+    });
+
+    return issues;
+  },
+};

package/src/engine/rules/aria-modal.js

@@ -0,0 +1,48 @@
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+function hasDialogRole(element) {
+  return (element.getAttribute('role') || '')
+    .toLowerCase()
+    .split(/\s+/)
+    .includes('dialog');
+}
+
+export const ariaModalRule = {
+  id: 'aria-modal',
+  name: 'ARIA modal dialog usage',
+  enabled: true,
+  description: 'Detects ARIA dialog/modal usage and invalid tabindex on dialog elements',
+  check(document) {
+    const issues = [];
+
+    document.querySelectorAll('[aria-modal], [role]').forEach((element) => {
+      if (!element.hasAttribute('aria-modal') && !hasDialogRole(element)) {
+        return;
+      }
+
+      issues.push({
+        severity: 'warning',
+        rule: 'aria-modal',
+        element: getElementSignature(element),
+        message: element.hasAttribute('aria-modal')
+          ? 'Element uses aria-modal for modal dialog behavior'
+          : 'Element uses ARIA dialog role instead of a native dialog element',
+        suggestion: 'Consider using the native <dialog> element for modal dialogs',
+        line: getLineNumber(element),
+      });
+    });
+
+    document.querySelectorAll('dialog[tabindex]').forEach((dialog) => {
+      issues.push({
+        severity: 'error',
+        rule: 'aria-modal',
+        element: getElementSignature(dialog),
+        message: '<dialog> element must not use tabindex',
+        suggestion: 'Remove tabindex from the <dialog> element',
+        line: getLineNumber(dialog),
+      });
+    });
+
+    return issues;
+  },
+};

package/src/engine/rules/aria-structure.js

@@ -0,0 +1,37 @@
+import { ARIA_STRUCTURE_ROLE_MAPPINGS } from '../aria-structure-role-mappings.js';
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+export const ariaStructureRule = {
+  id: 'aria-structure',
+  name: 'ARIA structure usage',
+  enabled: true,
+  description: 'Detects elements using ARIA structure roles that should use semantic elements',
+  check(document) {
+    const issues = [];
+
+    document.querySelectorAll('[role]').forEach((element) => {
+      const roles = element
+        .getAttribute('role')
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+
+      ARIA_STRUCTURE_ROLE_MAPPINGS.forEach(({ role, semanticElement, isSemanticMatch }) => {
+        if (!roles.includes(role) || isSemanticMatch(element)) {
+          return;
+        }
+
+        issues.push({
+          severity: 'warning',
+          rule: 'aria-structure',
+          element: getElementSignature(element),
+          message: `Element uses ARIA ${role} role instead of a semantic element`,
+          suggestion: `Consider using ${semanticElement} element instead`,
+          line: getLineNumber(element),
+        });
+      });
+    });
+
+    return issues;
+  },
+};

package/src/engine/rules/heading-hierarchy.js

@@ -0,0 +1,45 @@
+import { getLineNumber } from '../utils.js';
+
+export const headingHierarchyRule = {
+  id: 'heading-hierarchy',
+  name: 'Heading hierarchy issues',
+  enabled: true,
+  description: 'Detects improper heading hierarchy (e.g., h1 > h3 without h2)',
+  check(document) {
+    const issues = [];
+    const headings = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6'));
+
+    if (!document.querySelector('h1')) {
+      issues.push({
+        severity: 'warning',
+        rule: 'heading-hierarchy',
+        element: 'document',
+        message: 'Page does not have an h1 heading',
+        suggestion: 'Add one <h1> that describes the main topic of the page',
+        line: 0,
+      });
+    }
+
+    let previousLevel = 0;
+
+    headings.forEach((heading) => {
+      const currentLevel = parseInt(heading.tagName[1]);
+
+      // Check for skipped levels (except first heading)
+      if (previousLevel > 0 && currentLevel > previousLevel + 1) {
+        issues.push({
+          severity: 'warning',
+          rule: 'heading-hierarchy',
+          element: heading.textContent.substring(0, 50),
+          message: `Heading hierarchy skipped: ${previousLevel > 0 ? `<h${previousLevel}>` : 'start'} -> <${heading.tagName.toLowerCase()}>`,
+          suggestion: `Use <h${previousLevel + 1}> instead of <${heading.tagName.toLowerCase()}>`,
+          line: getLineNumber(heading),
+        });
+      }
+
+      previousLevel = currentLevel;
+    });
+
+    return issues;
+  },
+};

package/src/engine/rules/image-alt.js

@@ -0,0 +1,77 @@
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+function normalizeText(value) {
+  return value
+    .trim()
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+}
+
+export const imageAltRule = {
+  id: 'image-alt',
+  name: 'Image alternative text',
+  enabled: true,
+  description: 'Detects images without alt attributes and conflicting image labels',
+  check(document) {
+    const issues = [];
+
+    document.querySelectorAll('img').forEach((image) => {
+      const hasAltAttribute = image.hasAttribute('alt');
+      const altText = image.getAttribute('alt') || '';
+      const ariaLabel = image.getAttribute('aria-label');
+      const hasAriaLabel = ariaLabel !== null;
+
+      if (!hasAltAttribute) {
+        issues.push({
+          severity: 'error',
+          rule: 'image-alt',
+          element: getElementSignature(image),
+          message: 'Image is missing an alt attribute',
+          suggestion: 'Add an alt attribute that describes the image, or use alt="" for decorative images',
+          line: getLineNumber(image),
+        });
+      }
+
+      if (!hasAriaLabel) {
+        return;
+      }
+
+      if (!hasAltAttribute) {
+        issues.push({
+          severity: 'warning',
+          rule: 'image-alt',
+          element: getElementSignature(image),
+          message: 'Image uses aria-label without an alt attribute',
+          suggestion: 'Use the alt attribute as the image accessible name instead of aria-label',
+          line: getLineNumber(image),
+        });
+        return;
+      }
+
+      if (altText === '') {
+        issues.push({
+          severity: 'warning',
+          rule: 'image-alt',
+          element: getElementSignature(image),
+          message: 'Image uses aria-label while alt is empty',
+          suggestion: 'Remove aria-label for decorative images, or replace alt="" with meaningful alt text',
+          line: getLineNumber(image),
+        });
+        return;
+      }
+
+      if (normalizeText(ariaLabel) !== normalizeText(altText)) {
+        issues.push({
+          severity: 'warning',
+          rule: 'image-alt',
+          element: getElementSignature(image),
+          message: 'aria-label overrides image alt text',
+          suggestion: 'Remove aria-label and keep the accessible name in the alt attribute',
+          line: getLineNumber(image),
+        });
+      }
+    });
+
+    return issues;
+  },
+};

package/src/engine/rules/missing-form-labels.js

@@ -0,0 +1,49 @@
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+export const missingFormLabelsRule = {
+  id: 'missing-form-labels',
+  name: 'Form inputs without labels',
+  enabled: true,
+  description: 'Detects form inputs that are not properly labeled',
+  check(document) {
+    const issues = [];
+
+    document.querySelectorAll('input, textarea, select').forEach((input) => {
+      if (
+        input.tagName.toLowerCase() === 'input' &&
+        input.getAttribute('type')?.toLowerCase() === 'hidden'
+      ) {
+        return;
+      }
+
+      const id = input.id;
+      const name = input.name;
+      const ariaLabel = input.getAttribute('aria-label');
+      const ariaLabelledBy = input.getAttribute('aria-labelledby');
+      const wrappingLabel = input.closest('label');
+
+      if (id && document.querySelector(`label[for="${id}"]`)) {
+        return;
+      }
+
+      if (wrappingLabel) {
+        return;
+      }
+
+      if (ariaLabel || ariaLabelledBy) {
+        return;
+      }
+
+      issues.push({
+        severity: 'error',
+        rule: 'missing-form-labels',
+        element: getElementSignature(input),
+        message: 'Form input is not properly labeled',
+        suggestion: `Add label: <label for="${id || name}">Label text</label>`,
+        line: getLineNumber(input),
+      });
+    });
+
+    return issues;
+  },
+};