semantica11y 1.0.0

package/src/engine/rules/missing-key-landmark.js

@@ -0,0 +1,63 @@
+import { SEMANTIC_ROLE_MAPPINGS } from '../semantic-role-mappings.js';
+
+const REQUIRED_LANDMARK_ELEMENTS = ['header', 'main', 'footer'];
+
+function hasSemanticElement(document, element) {
+  return document.getElementsByTagName(element).length > 0;
+}
+
+function hasAriaRole(document, ariaRole) {
+  return Array.from(document.querySelectorAll('[role]')).some((element) =>
+    element
+      .getAttribute('role')
+      .toLowerCase()
+      .split(/\s+/)
+      .includes(ariaRole)
+  );
+}
+
+export const missingKeyLandmarkRule = {
+  id: 'missing-key-landmark',
+  name: 'Missing key landmark',
+  enabled: true,
+  description: 'Detects pages without key landmarks',
+  check(document) {
+    const issues = [];
+
+    SEMANTIC_ROLE_MAPPINGS
+      .filter(({ element }) => REQUIRED_LANDMARK_ELEMENTS.includes(element))
+      .forEach(({ element, ariaRole, missingMessage, missingSuggestion }) => {
+        const hasRequiredSemanticElement = hasSemanticElement(document, element);
+        const hasRequiredAriaRole = hasAriaRole(document, ariaRole);
+
+        if (hasRequiredSemanticElement || hasRequiredAriaRole) {
+          return;
+        }
+
+        issues.push({
+          severity: 'suggestion',
+          rule: 'missing-key-landmark',
+          element: '<body>',
+          message: missingMessage,
+          suggestion: missingSuggestion,
+          line: 1,
+        });
+      });
+
+    const hasHeading = document.querySelector('h1, h2, h3, h4, h5, h6');
+    const hasHeadingRole = hasAriaRole(document, 'heading');
+
+    if (!hasHeading && !hasHeadingRole) {
+      issues.push({
+        severity: 'suggestion',
+        rule: 'missing-key-landmark',
+        element: '<body>',
+        message: 'Page should have a heading',
+        suggestion: 'Add a heading element such as <h1> through <h6>',
+        line: 1,
+      });
+    }
+
+    return issues;
+  },
+};

package/src/engine/rules/missing-role-action.js

@@ -0,0 +1,77 @@
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+const ACTION_ROLES = ['button', 'checkbox', 'link', 'textbox'];
+
+function hasActionRole(element) {
+  const roles = (element.getAttribute('role') || '')
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(Boolean);
+
+  return roles.some((role) => ACTION_ROLES.includes(role));
+}
+
+function isNativeActionElement(element) {
+  const tagName = element.tagName.toLowerCase();
+
+  if (['button', 'select', 'textarea'].includes(tagName)) {
+    return true;
+  }
+
+  if (tagName === 'a') {
+    return element.hasAttribute('href');
+  }
+
+  if (tagName === 'input') {
+    return element.getAttribute('type')?.toLowerCase() !== 'hidden';
+  }
+
+  return false;
+}
+
+function createIssue(element, message) {
+  return {
+    severity: 'warning',
+    rule: 'missing-role-action',
+    element: getElementSignature(element),
+    message,
+    suggestion: 'Use a native action element such as <button> or <a>, or add an appropriate action role',
+    line: getLineNumber(element),
+  };
+}
+
+export const missingRoleActionRule = {
+  id: 'missing-role-action',
+  name: 'Missing role on focusable action',
+  enabled: true,
+  description: 'Detects non-semantic action elements that do not have an action role',
+  check(document) {
+    const issues = [];
+    const reportedElements = new Set();
+
+    document.querySelectorAll('[tabindex="0"]').forEach((element) => {
+      if (hasActionRole(element) || isNativeActionElement(element)) {
+        return;
+      }
+
+      issues.push(createIssue(element, 'Focusable element does not have an action role'));
+      reportedElements.add(element);
+    });
+
+    document.querySelectorAll('[onclick]').forEach((element) => {
+      if (
+        reportedElements.has(element) ||
+        hasActionRole(element) ||
+        isNativeActionElement(element)
+      ) {
+        return;
+      }
+
+      issues.push({
+        ...createIssue(element, 'Element has a click handler but does not have an action role'),
+      });
+    });
+
+    return issues;
+  },
+};

package/src/engine/rules/native-label.js

@@ -0,0 +1,113 @@
+import { getElementSignature, getLineNumber } from '../utils.js';
+
+const INPUT_VALUE_LABEL_TYPES = ['button', 'reset', 'submit'];
+const ALLOWED_ARIA_LABEL_EXTENSIONS = [
+  'opens in a new window',
+  'opens in new window',
+];
+
+function normalizeText(value) {
+  return value
+    .trim()
+    .replace(/[()[\].,:;–—-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+}
+
+function getLabelText(element, document) {
+  const id = element.id;
+  const explicitLabel = id ? document.querySelector(`label[for="${id}"]`) : null;
+  const wrappingLabel = element.closest('label');
+
+  return explicitLabel?.textContent.trim() || wrappingLabel?.textContent.trim() || '';
+}
+
+function getNativeText(element, document) {
+  const tagName = element.tagName.toLowerCase();
+
+  if (['button', 'a'].includes(tagName)) {
+    return element.textContent.trim();
+  }
+
+  if (tagName === 'input') {
+    const type = element.getAttribute('type')?.toLowerCase() || 'text';
+
+    if (INPUT_VALUE_LABEL_TYPES.includes(type)) {
+      return element.getAttribute('value')?.trim() || '';
+    }
+
+    return getLabelText(element, document);
+  }
+
+  if (['textarea', 'select'].includes(tagName)) {
+    return getLabelText(element, document);
+  }
+
+  return '';
+}
+
+function hasAllowedExtension(ariaLabel, nativeText) {
+  const normalizedAriaLabel = normalizeText(ariaLabel);
+  const normalizedNativeText = normalizeText(nativeText);
+
+  return normalizedAriaLabel.includes(normalizedNativeText);
+}
+
+function hasApprovedHelperText(ariaLabel, nativeText) {
+  const normalizedAriaLabel = normalizeText(ariaLabel);
+  const normalizedNativeText = normalizeText(nativeText);
+
+  if (!normalizedAriaLabel.startsWith(`${normalizedNativeText} `)) {
+    return false;
+  }
+
+  const extension = normalizedAriaLabel.slice(normalizedNativeText.length).trim();
+
+  return ALLOWED_ARIA_LABEL_EXTENSIONS.includes(extension);
+}
+
+export const nativeLabelRule = {
+  id: 'native-label',
+  name: 'Native label conflicts',
+  enabled: true,
+  description: 'Detects aria-label values that duplicate or conflict with native label text',
+  check(document) {
+    const issues = [];
+
+    document
+      .querySelectorAll('button[aria-label], a[href][aria-label], input[aria-label], textarea[aria-label], select[aria-label]')
+      .forEach((element) => {
+        const ariaLabel = element.getAttribute('aria-label') || '';
+        const nativeText = getNativeText(element, document);
+
+        if (!nativeText.trim()) {
+          return;
+        }
+
+        const isSameLabel = normalizeText(ariaLabel) === normalizeText(nativeText);
+
+        if (
+          !isSameLabel &&
+          (hasAllowedExtension(ariaLabel, nativeText) ||
+            hasApprovedHelperText(ariaLabel, nativeText))
+        ) {
+          return;
+        }
+
+        issues.push({
+          severity: isSameLabel ? 'warning' : 'error',
+          rule: 'native-label',
+          element: getElementSignature(element),
+          message: isSameLabel
+            ? 'Unnecessary aria-label duplicates native label text'
+            : 'aria-label does not match native label text',
+          suggestion: isSameLabel
+            ? 'Remove the aria-label and use the native label text'
+            : 'Update aria-label to match the visible label, or remove it and rely on native text',
+          line: getLineNumber(element),
+        });
+      });
+
+    return issues;
+  },
+};

package/src/engine/semantic-role-mappings.js

@@ -0,0 +1,51 @@
+export const SEMANTIC_ROLE_MAPPINGS = [
+  {
+    element: 'header',
+    ariaRole: 'banner',
+    message: 'Element appears to be used for page header',
+    missingMessage: 'Page should have a header landmark',
+    missingSuggestion: 'Add a <header> element',
+  },
+  {
+    element: 'footer',
+    ariaRole: 'contentinfo',
+    message: 'Element appears to be used for page footer',
+    missingMessage: 'Page should have a footer landmark',
+    missingSuggestion: 'Add a <footer> element',
+  },
+  {
+    element: 'nav',
+    ariaRole: 'navigation',
+    message: 'Element appears to be used for navigation',
+    missingMessage: 'Page should have a navigation landmark',
+    missingSuggestion: 'Add a <nav> element',
+  },
+  {
+    element: 'main',
+    ariaRole: 'main',
+    message: 'Element appears to be used for main content',
+    missingMessage: 'Page should have a main content landmark',
+    missingSuggestion: 'Add a <main> element',
+  },
+  {
+    element: 'aside',
+    ariaRole: 'complementary',
+    message: 'Element appears to be used for complementary content',
+    missingMessage: 'Page should have a complementary content landmark',
+    missingSuggestion: 'Add an <aside> element',
+  },
+  {
+    element: 'article',
+    ariaRole: 'article',
+    message: 'Element appears to be used for article content',
+    missingMessage: 'Page should have an article landmark',
+    missingSuggestion: 'Add an <article> element',
+  },
+  {
+    element: 'section',
+    ariaRole: 'region',
+    message: 'Element appears to be used for a page section',
+    missingMessage: 'Page should have a section landmark',
+    missingSuggestion: 'Add a <section> element',
+  },
+];

package/src/engine/utils.js

@@ -0,0 +1,27 @@
+/**
+ * Helper function to get approximate line number of an element
+ * (JSDOM doesn't provide line numbers, so this is a placeholder)
+ */
+export function getLineNumber(element) {
+  // In a real implementation, you might track this during DOM traversal
+  return 0;
+}
+
+export function getElementSignature(element) {
+  const attributes = [
+    'id',
+    'class',
+    'role',
+    'tabindex',
+    'aria-label',
+    'aria-expanded',
+    'aria-modal',
+  ]
+    .map((attribute) => {
+      const value = element.getAttribute(attribute);
+      return value ? ` ${attribute}="${value}"` : '';
+    })
+    .join('');
+
+  return `<${element.tagName.toLowerCase()}${attributes}>`;
+}

package/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * Semantica11y - HTML Semantic and ARIA Analysis Engine
+ * A JavaScript library to check webpages for ARIA and non-semantic HTML elements
+ * with suggestions for semantic alternatives.
+ */
+
+export { Analyzer } from './analyzer.js';
+export { RuleEngine } from './engine/index.js';
+export { DEFAULT_RULES, CUSTOM_RULES } from './engine/definitions.js';
+export {
+  exportTextReport,
+  formatConsoleReport,
+  printConsoleReport,
+} from './engine/reporter/index.js';