@surea11y/core 1.0.0

package/src/checks/automatic/aria-role-name-present.js

@@ -0,0 +1,201 @@
+'use strict';
+
+/**
+ * Generic name-presence rule for selected ARIA composite/widget roles that should expose an accessible name.
+ *
+ * Notes:
+ * - This rule intentionally focuses on author-provided naming mechanisms:
+ *   aria-label, aria-labelledby, and title.
+ * - It does NOT treat descendant text content as a valid name source for these roles
+ *   (to avoid false passes from labelled children inside composite widgets).
+ * - Eligibility is based on helpers.isAccTreeEligible(node, ctx) per engine checks.
+ */
+
+const id = 'aria-role-name-present';
+
+const meta = {
+  title: 'ARIA widget/container roles have an accessible name',
+  description: 'Checks that selected ARIA widget/container roles expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'ariaRoleNamePresent_title',
+    descriptionKey: 'ariaRoleNamePresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'navigation', 'atomic', 'automatic', 'name'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: {
+    facetsBySc: {
+      '4.1.2': ['aria-role-name-present']
+    }
+  }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll = helpers && typeof helpers.queryAll === 'function'
+    ? helpers.queryAll
+    : (sel, rt) => {
+        try {
+          const scope = rt || safeRoot;
+          return scope && scope.querySelectorAll ? Array.from(scope.querySelectorAll(sel)) : [];
+        } catch {
+          return [];
+        }
+      };
+
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
+
+  const getAriaLabelledByInfo =
+    helpers && typeof helpers.getAriaLabelledByInfo === 'function' ? helpers.getAriaLabelledByInfo : null;
+
+  const normalizeWs = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+
+  const getAttr = (el, name) => {
+    try {
+      if (!el || !el.getAttribute) return '';
+      return normalizeWs(el.getAttribute(name));
+    } catch {
+      return '';
+    }
+  };
+
+
+  // aria-labelledby resolution: delegate to the shared helper (used by
+  // button-name-present et al.), which correctly includes hidden/aria-hidden
+  // referenced nodes per the Accessible Name and Description Computation
+  // spec (a hidden node directly referenced by aria-labelledby still
+  // supplies its text — this is a standard visually-hidden-label pattern).
+  const resolveLabelledby = (el, maxRefs) => {
+    if (!getAriaLabelledByInfo) return '';
+    try {
+      const info = getAriaLabelledByInfo(el, ctx, { maxRefs: Math.max(1, maxRefs || 8) });
+      return info && info.present ? normalizeWs(info.value) : '';
+    } catch {
+      return '';
+    }
+  };
+
+  const isEligible = (el) => {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  };
+
+  // Frozen allowlist of roles to check in this generic rule.
+  // (Keep this small, explicit, and standards-based for determinism.)
+  const roleSet = new Set([
+    'scrollbar',
+    'toolbar',
+    'tablist',
+    'radiogroup',
+    'tree',
+    'grid',
+    'menu',
+    'menubar',
+    'meter',
+    'progressbar'
+  ]);
+
+  const selector =
+    '[role="scrollbar"],[role="toolbar"],[role="tablist"],[role="radiogroup"],[role="tree"],[role="grid"],[role="menu"],[role="menubar"],[role="meter"],[role="progressbar"]';
+
+  const nodes = (() => {
+    try {
+      return (queryAllSmart ? queryAllSmart(selector, safeRoot) : queryAll(selector, safeRoot)) || [];
+    } catch {
+      return queryAll(selector, safeRoot);
+    }
+  })();
+
+  if (!nodes.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    // Role normalization + allowlist check (defensive).
+    const role = (() => {
+      try {
+        return normalizeWs(el.getAttribute('role')).toLowerCase();
+      } catch {
+        return '';
+      }
+    })();
+    if (!roleSet.has(role)) continue;
+
+    if (!isEligible(el)) continue;
+
+    applicableCount += 1;
+
+    const ariaLabel = getAttr(el, 'aria-label');
+    const labelled = ariaLabel ? '' : resolveLabelledby(el, 8);
+
+    const title = ariaLabel || labelled ? '' : getAttr(el, 'title');
+
+    const ok = !!(ariaLabel || labelled || title);
+    if (ok) continue;
+
+    const eligInfo = getEligibilityInfo ? (() => {
+      try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; }
+    })() : null;
+
+    const baseOccurrence = {
+      summary: 'This element has no accessible name.',
+      hint: 'Provide aria-label or aria-labelledby (preferred), or a non-empty title attribute.',
+      i18n: {
+        summaryKey: 'ariaRoleNamePresent_summary_fail',
+        hintKey: 'ariaRoleNamePresent_hint_fail',
+        params: { role }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        details: {
+          reasonCode: 'name_missing',
+          role,
+          nameSourcesChecked: ['aria-label', 'aria-labelledby', 'title']
+        }
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push({ selector: '', html: '', ...baseOccurrence });
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  if (!occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-roles-valid.js

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * @check aria-roles-valid
+ * @atomic true
+ * @summary An explicit role attribute must resolve to a real, non-abstract ARIA role
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to any element with a non-empty role="" attribute in the composed DOM.
+ * @expectation
+ *   The role attribute's first token (the role actually used by assistive technology;
+ *   later space-separated tokens are author-supplied fallbacks and are not evaluated
+ *   here) must be a real WAI-ARIA role name, and must not be an abstract role
+ *   (abstract roles exist only for the specification's own role taxonomy and must
+ *   never be used directly in markup).
+ * @implementation-notes
+ * - Unlike this engine's accessible-name rules, ARIA validity is a static markup
+ *   property independent of current visibility/eligibility, so this rule does not
+ *   gate on isAccTreeEligible: an invalid role is a defect whether or not the
+ *   element happens to be hidden right now.
+ */
+
+const id = 'aria-roles-valid';
+
+const meta = {
+  title: 'role attribute must be a valid, non-abstract ARIA role',
+  description: 'Checks that an explicit role="" attribute resolves to a real, non-abstract WAI-ARIA role.',
+  i18n: {
+    titleKey: 'ariaRolesValid_title',
+    descriptionKey: 'ariaRolesValid_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['aria-role-valid'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+  if (!ariaHelpers) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const role = ariaHelpers.getExplicitRole(el);
+    if (!role) continue; // role="" or whitespace-only: not this rule's concern
+
+    applicableCount += 1;
+
+    const isAbstract = ariaHelpers.isAbstractRole(role);
+    const isKnown = ariaHelpers.isKnownRole(role);
+
+    if (isKnown && !isAbstract) continue;
+
+    const reasonCode = !isKnown ? 'ARIA_ROLE_INVALID' : 'ARIA_ROLE_ABSTRACT';
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: !isKnown
+        ? 'The role attribute value is not a recognized ARIA role.'
+        : 'The role attribute value is an abstract ARIA role, which must not be used directly.',
+      hint: !isKnown
+        ? 'Use a valid ARIA role token, or remove the role attribute if none applies.'
+        : 'Replace this abstract role with a concrete role appropriate for the widget/structure.',
+      i18n: {
+        summaryKey: !isKnown
+          ? 'ariaRolesValid_summary_invalid'
+          : 'ariaRolesValid_summary_abstract',
+        hintKey: !isKnown
+          ? 'ariaRolesValid_hint_invalid'
+          : 'ariaRolesValid_hint_abstract',
+        params: { role }
+      },
+      data: {
+        details: { reasonCode, role }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-valid-attr-value.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * @check aria-valid-attr-value
+ * @atomic true
+ * @summary Every recognized aria-* attribute must have a value matching its declared type
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to any element carrying at least one recognized aria-* attribute
+ *   (unrecognized attribute names are aria-valid-attr's concern,
+ *   not evaluated here).
+ * @expectation
+ *   Each attribute's value conforms to its WAI-ARIA-declared value type:
+ *   boolean ("true"/"false"), tristate ("true"/"false"/"mixed"), a token
+ *   from a fixed enumerated set, an integer, a real number, or a non-empty
+ *   ID reference (list) that resolves to an existing element in the
+ *   document.
+ * @implementation-notes
+ * - Not gated on isAccTreeEligible: this is a static markup property.
+ * - ID-reference resolution (added 2026-07-20, see aria-helpers.js's
+ *   idExists) only flags idref-list attributes (aria-labelledby,
+ *   aria-describedby, aria-controls, aria-owns, etc.) when NONE of the
+ *   space-separated ids resolve — a partially-dangling list (some ids
+ *   exist, some don't) is left unflagged. Verified 2026-07-21 directly
+ *   against a widely-used reference engine's own `validateAttrValue` source:
+ *   this is not a conservative guess, it's an exact match for that engine's
+ *   own behavior (`idrefs(vNode, attr).some(node => !!node)` — that engine
+ *   itself only invalidates when every token fails to resolve). Single-idref
+ *   attributes (aria-activedescendant, aria-errormessage) are flagged
+ *   whenever their one id doesn't resolve, also matching that engine's `idref`
+ *   case exactly.
+ */
+
+const id = 'aria-valid-attr-value';
+
+const meta = {
+  title: 'aria-* attribute values must match their declared type',
+  description: 'Checks that every recognized aria-* attribute has a value conforming to its WAI-ARIA-declared value type (boolean, tristate, token, integer, number, or ID reference).',
+  i18n: {
+    titleKey: 'ariaValidAttrValue_title',
+    descriptionKey: 'ariaValidAttrValue_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['aria-attr-value-valid'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+  if (!ariaHelpers) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('*', safeRoot) : helpers.queryAll('*', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.attributes || !el.getAttribute) continue;
+
+    let invalid = null;
+    const attrs = el.attributes;
+    for (let i = 0; i < attrs.length; i++) {
+      const name = String(attrs[i].name || '').toLowerCase();
+      if (name.slice(0, 5) !== 'aria-') continue;
+      if (!ariaHelpers.isValidAriaAttrName(name)) continue; // aria-valid-attr's concern
+
+      applicableCount += 1;
+
+      const rawValue = el.getAttribute(name);
+      const result = ariaHelpers.validateAttrValue(name, rawValue);
+      if (!result.valid) {
+        if (!invalid) invalid = [];
+        invalid.push({ name, value: rawValue == null ? '' : String(rawValue), reason: result.reason });
+      }
+    }
+
+    if (!invalid || !invalid.length) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    for (const item of invalid) {
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: 'This element has an ARIA attribute with an invalid value.',
+        hint: 'Use a value that matches the attribute’s expected type (see the WAI-ARIA specification for this attribute).',
+        i18n: {
+          summaryKey: 'ariaValidAttrValue_summary_fail',
+          hintKey: 'ariaValidAttrValue_hint_fail',
+          params: { attr: item.name, value: item.value }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ATTR_VALUE_INVALID', attr: item.name, value: item.value, valueReason: item.reason }
+        }
+      });
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-valid-attr.js

@@ -0,0 +1,109 @@
+'use strict';
+
+/**
+ * @check aria-valid-attr
+ * @atomic true
+ * @summary Every aria-* attribute present must be a real, defined ARIA attribute
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to any element in the composed DOM that carries at least one
+ *   attribute whose name starts with "aria-".
+ * @expectation
+ *   Each aria-* attribute name is a real attribute defined by the WAI-ARIA
+ *   specification (catches typos / made-up attribute names, which are
+ *   silently ignored by assistive technology and therefore a real,
+ *   deterministic defect).
+ * @implementation-notes
+ * - Distinct from aria-valid-attr-value (which validates the VALUE
+ *   of a recognized attribute) — this rule only validates the attribute
+ *   NAME.
+ * - Not gated on isAccTreeEligible: this is a static markup property.
+ */
+
+const id = 'aria-valid-attr';
+
+const meta = {
+  title: 'aria-* attributes must be real, defined ARIA attributes',
+  description: 'Checks that every aria-* attribute name present in the DOM is a real attribute defined by the WAI-ARIA specification.',
+  i18n: {
+    titleKey: 'ariaValidAttr_title',
+    descriptionKey: 'ariaValidAttr_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['aria-attr-name-valid'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+  if (!ariaHelpers) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('*', safeRoot) : helpers.queryAll('*', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.attributes) continue;
+
+    let invalidNames = null;
+    const attrs = el.attributes;
+    for (let i = 0; i < attrs.length; i++) {
+      const name = String(attrs[i].name || '').toLowerCase();
+      if (name.slice(0, 5) !== 'aria-') continue;
+
+      applicableCount += 1;
+
+      if (!ariaHelpers.isValidAriaAttrName(name)) {
+        if (!invalidNames) invalidNames = [];
+        invalidNames.push(name);
+      }
+    }
+
+    if (!invalidNames || !invalidNames.length) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    for (const name of invalidNames) {
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: 'This element has an attribute that is not a recognized ARIA attribute.',
+        hint: 'Correct the attribute name (check for typos), or remove it if not needed.',
+        i18n: {
+          summaryKey: 'ariaValidAttr_summary_fail',
+          hintKey: 'ariaValidAttr_hint_fail',
+          params: { attr: name }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ATTR_INVALID', attr: name }
+        }
+      });
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/autocomplete-valid.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * @check autocomplete-valid
+ * @atomic true
+ * @summary A non-empty autocomplete attribute must follow the WHATWG autofill grammar
+ * @standard WCAG 2.2
+ * @sc 1.3.5
+ * @applicability
+ *   Applies to form controls (input, select, textarea) with a non-empty
+ *   autocomplete attribute.
+ * @expectation
+ *   The value is "on"/"off" alone, or a well-formed autofill detail
+ *   token list: an optional "section-*" token, then an optional
+ *   "shipping"/"billing" token, then an optional contact-modality token
+ *   (home/work/mobile/fax/pager/impp), then exactly one recognized
+ *   field-name token (name, email, street-address, cc-number, tel, ...),
+ *   optionally followed by "webauthn". A malformed value means the field
+ *   is not reliably identified for assistive technology that relies on
+ *   autocomplete to describe the expected input purpose.
+ * @implementation-notes
+ * - Implements the structural shape of the WHATWG autofill grammar
+ *   (section/mode/contact-modality prefixes + one field-name token, in
+ *   order) with the full fixed field-name vocabulary from the HTML
+ *   Standard, rather than validating every field-specific constraint
+ *   (e.g. which contact-modality tokens are legal for which field
+ *   names) — matches this engine's established "deliberately scoped"
+ *   precedent (see aria-helpers.js) for keeping high-confidence fail
+ *   without reimplementing the entire spec.
+ */
+
+const id = 'autocomplete-valid';
+
+const meta = {
+  title: 'autocomplete attribute must be a valid autofill value',
+  description: 'Checks that a non-empty autocomplete attribute is "on"/"off" or a well-formed autofill detail token list.',
+  i18n: {
+    titleKey: 'autocompleteValid_title',
+    descriptionKey: 'autocompleteValid_description'
+  },
+  helpUrl: null,
+  tags: ['wcag21aa', 'wcag135', 'forms', 'atomic', 'automatic'],
+  wcagSc: ['1.3.5'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.3.5', title: 'Identify Input Purpose', conformanceLevel: 'AA' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.3.5': ['autocomplete-valid'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  // Declared inside runInPage — see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  const FIELD_NAMES = new Set([
+    'name', 'honorific-prefix', 'given-name', 'additional-name', 'family-name', 'honorific-suffix',
+    'nickname', 'username', 'new-password', 'current-password', 'one-time-code', 'organization-title',
+    'organization', 'street-address', 'address-line1', 'address-line2', 'address-line3',
+    'address-level4', 'address-level3', 'address-level2', 'address-level1', 'country', 'country-name',
+    'postal-code', 'cc-name', 'cc-given-name', 'cc-additional-name', 'cc-family-name', 'cc-number',
+    'cc-exp', 'cc-exp-month', 'cc-exp-year', 'cc-csc', 'cc-type', 'transaction-currency',
+    'transaction-amount', 'language', 'bday', 'bday-day', 'bday-month', 'bday-year', 'sex',
+    'tel', 'tel-country-code', 'tel-national', 'tel-area-code', 'tel-local', 'tel-extension',
+    'email', 'impp', 'url', 'photo'
+  ]);
+  const CONTACT_MODALITY = new Set(['home', 'work', 'mobile', 'fax', 'pager', 'impp']);
+
+  function isValidAutocomplete(raw) {
+    const tokens = raw.trim().toLowerCase().split(/\s+/).filter(Boolean);
+    if (!tokens.length) return false;
+    if (tokens.length === 1 && (tokens[0] === 'on' || tokens[0] === 'off')) return true;
+
+    let i = 0;
+    if (tokens[i] && tokens[i].startsWith('section-') && tokens[i].length > 'section-'.length) i += 1;
+    if (tokens[i] === 'shipping' || tokens[i] === 'billing') i += 1;
+    if (CONTACT_MODALITY.has(tokens[i])) i += 1;
+
+    let end = tokens.length;
+    if (tokens[end - 1] === 'webauthn') end -= 1;
+
+    const remaining = tokens.slice(i, end);
+    if (remaining.length !== 1) return false;
+    return FIELD_NAMES.has(remaining[0]);
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('input, select, textarea', safeRoot) : helpers.queryAll('input, select, textarea', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    const raw = String(el.getAttribute('autocomplete') || '').trim();
+    if (!raw) continue;
+
+    applicableCount += 1;
+
+    if (isValidAutocomplete(raw)) continue;
+
+    const tag = el.tagName.toLowerCase();
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This autocomplete attribute value is not a valid autofill value.',
+      hint: 'Use "on"/"off", or a valid autofill token list (e.g. "shipping street-address", "cc-number").',
+      i18n: {
+        summaryKey: 'autocompleteValid_summary_fail',
+        hintKey: 'autocompleteValid_hint_fail',
+        params: { element: tag, value: raw }
+      },
+      data: {
+        details: { reasonCode: 'AUTOCOMPLETE_VALUE_INVALID', element: tag, value: raw }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'moderate', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };