@surea11y/core 1.1.1 → 1.2.0

package/src/core/aria-helpers.js

@@ -38,6 +38,16 @@ function createAriaHelpers(opts, shared) {
     const trim = (shared && shared.trim) || ((v) => (v == null ? '' : String(v)).trim());
     const lower = (v) => trim(v).toLowerCase();
     const ariaDocument = opts && opts.document;
+    // Same normalization as createDomHelpers's `roots` (src/core/dom-helpers.js)
+    // -- opts.root accepts a single element or an array (multi-region
+    // contextSelector support). Used to bound hasLandmarkScopingAncestor's
+    // ancestor walk to the scanned scope; see that function below.
+    const ariaRoots = (() => {
+        const r = opts && opts.root;
+        if (Array.isArray(r)) return r.filter((x) => x && typeof x === 'object');
+        if (r && typeof r === 'object') return [r];
+        return [];
+    })();
 
     // Existence check for a single ID token — never throws, returns false
     // (not "unknown") when the document isn't available so callers degrade
@@ -75,25 +85,70 @@ function createAriaHelpers(opts, shared) {
         return false;
     }
 
-    // Used for <header>/<footer>'s own conditional implicit role: per the
-    // W3C ARIA-in-HTML spec (matching a widely-used reference engine's own
-    // element-spec table for "header"/"footer" implicit-role functions, which check
-    // getSectioningContentPlusMainSelector — a fixed HTML content-type list,
-    // not a deep accname-style computation), a <header>/<footer> is only a
-    // "banner"/"contentinfo" landmark when it is NOT nested inside sectioning
-    // content (article/aside/nav/section) or <main>; nested, its implicit
-    // role is generic/null instead. Simplified to a tag-name ancestor walk
-    // (skipping that engine's additional role=article/complementary/navigation/
-    // region/main equivalences) — deliberately pragmatic, matching this
-    // table's existing precedent (hasAccessibleNameHint above takes the same
-    // "close enough, tag-based" approach rather than a full spec re-implementation).
-    function hasSectioningAncestor(el) {
+    // Shared "does this element have a landmark-scoping ancestor" primitive
+    // — <header>'s "banner", <footer>'s "contentinfo", and <aside>'s
+    // "complementary" implicit roles are all conditioned on the same W3C
+    // ARIA-in-HTML exclusion: suppressed when nested inside sectioning
+    // content (article/aside/nav/section), and for header/footer only,
+    // also suppressed when nested inside <main> (pass includeMain: true).
+    // <aside> itself omits <main> from its own exclusion list — see the
+    // `aside` case in getElementRoleKey below — so callers must pass the
+    // right includeMain for the role they're computing.
+    //
+    // ROLE-AWARE, not tag-only: an ancestor's bare TAG only counts when it
+    // has NO role attribute at all; once ANY role attribute is present,
+    // only that attribute's own (first-token) value decides membership —
+    // matching a widely-used reference engine's real
+    // getSectioningContentSelector/getSectioningContentPlusMainSelector,
+    // verified 2026-07-30 by reading that engine's source directly:
+    // `${tag}:not([role])` for the tag-based branch, OR'd with a wholly
+    // separate ` [role=article], [role=complementary], [role=navigation],
+    // [role=region]` branch (plus `, main:not([role]), [role=main]` for
+    // the plus-main variant) — never a tag-AND-role intersection.
+    //
+    // This replaced a tag-name-only ancestor walk (used only for <header>,
+    // and separately re-duplicated with the same tag-only bug across 6
+    // manual landmark-check files — see each file's own delegation to
+    // helpers.hasLandmarkScopingAncestor now) that missed a real page:
+    // handsontable.com's docs-assistant side panel is an
+    // <aside role="dialog"> containing its own <header>. role="dialog" is
+    // not one of the four scoping roles, so per spec the nested <header>
+    // DOES keep its implicit "banner" role (confirmed against that
+    // reference engine's real output via a minimal repro) — but the old
+    // tag-only check unconditionally suppressed it purely because the
+    // ancestor TAG was <aside>, regardless of its role override. A real
+    // false negative in landmark-no-duplicate-banner/landmark-unique,
+    // found via the cross-engine comparisons project 2026-07-30.
+    const LANDMARK_SCOPING_TAGS = new Set(['article', 'aside', 'nav', 'section']);
+    const LANDMARK_SCOPING_ROLE_TOKENS = new Set(['article', 'complementary', 'navigation', 'region']);
+
+    function isLandmarkScopingAncestorElement(el, includeMain) {
+        const tag = lower(el.tagName || '');
+        const roleAttr = getAttr(el, 'role');
+        if (roleAttr == null) {
+            // No role attribute at all: falls back to the plain HTML tag.
+            if (LANDMARK_SCOPING_TAGS.has(tag)) return true;
+            return includeMain && tag === 'main';
+        }
+        // A role attribute is present (even empty/invalid) — the element's
+        // bare TAG no longer counts; only an explicit, scoping-relevant
+        // role value does.
+        const token = trim(roleAttr).split(/\s+/)[0].toLowerCase();
+        if (LANDMARK_SCOPING_ROLE_TOKENS.has(token)) return true;
+        return includeMain && token === 'main';
+    }
+
+    function hasLandmarkScopingAncestor(el, opts) {
         if (!isElement(el)) return false;
+        const includeMain = !!(opts && opts.includeMain);
         let cur = el.parentElement;
         let guard = 0;
         while (cur && guard++ < 200) {
-            const t = lower(cur.tagName || '');
-            if (t === 'article' || t === 'aside' || t === 'main' || t === 'nav' || t === 'section') return true;
+            if (isLandmarkScopingAncestorElement(cur, includeMain)) return true;
+            // Don't climb past the scanned scope -- a contextSelector-scoped
+            // (or fragment) scan should never let ancestry OUTSIDE the
+            // analyzed subtree affect a role computed WITHIN it.
+            if (ariaRoots.includes(cur)) break;
             cur = cur.parentElement;
         }
         return false;
@@ -749,14 +804,16 @@ function createAriaHelpers(opts, shared) {
         if (tag === 'header') {
             // <header>'s own implicit role is conditional: "banner" when
             // top-level (not nested inside sectioning content/<main>),
-            // generic/null when nested — see hasSectioningAncestor above.
+            // generic/null when nested — see hasLandmarkScopingAncestor
+            // above (includeMain: true, matching <header>'s real exclusion
+            // list, which does include <main>).
             // role="banner" restated is only a no-op restatement of the
             // native role (and therefore permitted) at the top level; a
             // widely-used reference engine's own allowedRoles array for
             // <header> doesn't include 'banner'
             // at all (reached only via the native-role-match branch), same
             // shape as <section>'s 'region'.
-            return hasSectioningAncestor(el) ? 'header' : 'header[toplevel]';
+            return hasLandmarkScopingAncestor(el, { includeMain: true }) ? 'header' : 'header[toplevel]';
         }
 
         if (tag === 'label') {
@@ -899,7 +956,14 @@ function createAriaHelpers(opts, shared) {
         getRequiredOwnedRoles,
         getRequiredContextRoles,
         isRoleAllowedOnElement,
-        getContainmentRole
+        getContainmentRole,
+
+        // Shared "does this element have a landmark-scoping ancestor"
+        // primitive — see its own header comment above. Re-exported at
+        // helpers' top level too (src/core/dom-helpers.js), matching
+        // getLandmarkNameInfo's precedent, for the manual landmark-check
+        // files that used to each carry their own (buggy, tag-only) copy.
+        hasLandmarkScopingAncestor
     };
 }
 

package/src/core/dom-helpers.js

@@ -120,6 +120,11 @@ function createDomHelpers(opts) {
     // opt out with includeHiddenElements:true.
     const includeHiddenElements = !!(opts && opts.includeHiddenElements === true);
     const excludeSelectors = Array.isArray(opts && opts.excludeSelectors) ? opts.excludeSelectors : [];
+    // Default off: explicit opt-in for "this scan target was never meant to
+    // represent a real page" (e.g. a raw component fragment parsed on its
+    // own), regardless of whether document.documentElement happens to be in
+    // scope. See isWholeDocumentScope() below.
+    const fragment = !!(opts && opts.fragment === true);
 
     // Rule-scoped excludes (engineOptions.rules[ruleId].excludeSelectors), set
     // by dom-runner.js immediately before invoking each rule's applicability/
@@ -1092,7 +1097,8 @@ function createDomHelpers(opts) {
         'templateContent',
         'nonRenderedElement',
         'inputHidden',
-        'visibilityHidden'
+        'visibilityHidden',
+        'contentVisibilityHidden'
     ]);
 
     function queryAllSmart(sel) {
@@ -1109,6 +1115,23 @@ function createDomHelpers(opts) {
                     for (const r of reasons) {
                         if (HARD_HIDDEN_REASONS.has(r)) return false;
                     }
+
+                    // `isAccTreeEligible` can short-circuit on an inert ancestor
+                    // before it reaches an outer hard-hidden ancestor (e.g.
+                    // display:none wrapper). In that case the node is still
+                    // structurally hidden and should be excluded by the default
+                    // hidden-content policy.
+                    if (reasons.includes('inert')) {
+                        const domVis = isDomVisibleEligible(el, null, {
+                            visibilityMode: 'styleOnly',
+                            disableGeometry: true,
+                            ignoreOpacity: true
+                        });
+                        const domReasons = Array.isArray(domVis && domVis.reasons) ? domVis.reasons : [];
+                        for (const r of domReasons) {
+                            if (HARD_HIDDEN_REASONS.has(r)) return false;
+                        }
+                    }
                     return true;
                 } catch {
                     return true;
@@ -3685,6 +3708,36 @@ function createDomHelpers(opts) {
             let node = el;
             let safety = 0;
 
+            // Only apply the "stop climbing once we reach a contextSelector-
+            // matched root" shortcut when there's a single (or no) matched
+            // root -- resolveContextRoots() falls back to `[documentElement]`
+            // when no contextSelector is given, so this is the overwhelmingly
+            // common case and behaves exactly as before.
+            //
+            // With MULTIPLE matched roots (multi-region contextSelector
+            // scans), stopping there without recording anything about which
+            // root produced an ambiguous, non-unique selector string for two
+            // structurally-identical regions -- a real, confirmed bug (found
+            // 2026-07-29 via the cross-engine comparisons project): two
+            // wrapper <div>s, each containing two identical ".widget"
+            // sections scanned via `contextSelector: '.widget'`, produced the
+            // *same* selector string ("section:nth-of-type(1) > div > div >
+            // button") for the equivalent button in each wrapper --
+            // resolving to 2 elements instead of 1 when queried, and pointing
+            // at the wrong one for at least one of the two occurrences. The
+            // existing `el.matches(candidate)` safety check below couldn't
+            // catch this: it only verifies THIS element matches the string,
+            // never that the string is unique document-wide.
+            //
+            // Fix: when multiple roots are in play, don't stop early --
+            // keep climbing (same as the always-correct no-contextSelector
+            // path) until finding a genuinely unique anchor or reaching the
+            // true document root, which is always singular. That restores
+            // the invariant the final safety-check comment below relies on,
+            // rather than needing a separate (more expensive) document-wide
+            // uniqueness re-check.
+            const stopAtMatchedRoot = roots.length <= 1;
+
             while (node && node.nodeType === 1 && safety++ < 20) {
                 let anchor = null;
 
@@ -3724,7 +3777,7 @@ function createDomHelpers(opts) {
                     parts.unshift(nthOfType(node));
                 }
 
-                if (!node.parentElement || roots.includes(node)) break;
+                if (!node.parentElement || (stopAtMatchedRoot && roots.includes(node))) break;
                 node = node.parentElement;
             }
 
@@ -3743,7 +3796,12 @@ function createDomHelpers(opts) {
             // position relative to its own parent via `>` (child, not
             // descendant) combinators, so a correctly-matching chain can
             // only resolve to one element short of a malformed document
-            // (e.g. two <html> roots). Re-deriving that guarantee via a
+            // (e.g. two <html> roots) -- true as long as the walk above
+            // never stops short of a genuinely unique anchor/root, which is
+            // exactly what `stopAtMatchedRoot` now guarantees (see its own
+            // comment above; a multi-root contextSelector scan stopping
+            // early used to violate this invariant silently). Re-deriving
+            // that guarantee via a
             // document-wide :nth-of-type scan was measured to cost O(total
             // same-tag siblings) per call — pathological on pages with many
             // flat, unidentified siblings (e.g. hundreds of unlabeled
@@ -4069,6 +4127,22 @@ function createDomHelpers(opts) {
         {trim}
     );
 
+    // For rules whose check is inherently about the WHOLE page (does the
+    // page have a title? a declared language? a way to skip repeated
+    // blocks?) rather than about elements found within a scanned subtree --
+    // these can't be answered correctly by scoping via queryAllSmart/ctx.root
+    // the way per-element checks can, since a subtree that never had (and
+    // was never meant to have) e.g. its own <title> shouldn't be faulted for
+    // lacking one. `false` when `fragment:true` was explicitly set, or when
+    // `contextSelector` scoped this run narrower than the whole document
+    // (roots doesn't include document.documentElement); `true` in the
+    // default/unscoped case, so this is a no-op for the overwhelming
+    // majority of existing (whole-page) scans.
+    function isWholeDocumentScope() {
+        if (fragment) return false;
+        return roots.includes(document.documentElement);
+    }
+
     return {
         // Existing query/snippet utilities
         queryAll,
@@ -4084,6 +4158,7 @@ function createDomHelpers(opts) {
         isExcluded,
         isAccTreeEligible,
         isDomVisibleEligible,
+        isWholeDocumentScope,
 
         // Engine-internal: sets which rule's rule-scoped excludeSelectors
         // (engineOptions.rules[ruleId].excludeSelectors) are currently in
@@ -4108,6 +4183,16 @@ function createDomHelpers(opts) {
         // see getLandmarkNameInfo's own header comment for why this replaced 7 duplicated copies)
         getLandmarkNameInfo,
 
+        // "Does this element have a landmark-scoping ancestor" (role-aware
+        // sectioning-content/<main> check backing <header>/<footer>/<aside>'s
+        // conditional implicit roles) -- re-exported from aria helpers at
+        // this top level, matching getLandmarkNameInfo just above, so the
+        // manual landmark-check files that used to each carry their own
+        // (buggy, tag-only) copy can call helpers.hasLandmarkScopingAncestor
+        // directly. See aria.hasLandmarkScopingAncestor's own header comment
+        // in src/core/aria-helpers.js for the full algorithm and rationale.
+        hasLandmarkScopingAncestor: aria.hasLandmarkScopingAncestor,
+
         // Name / description
         getAccessibleNameInfo,
         getAccessibleDescriptionInfo,

package/src/core/dom-runner.js

@@ -52,6 +52,9 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
     // unless the caller explicitly opts in.
     const includeHiddenElements = !!(engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true);
     const excludeSelectors = normalizeSelectorList(engineOptionsResolved && engineOptionsResolved.excludeSelectors);
+    // Default off: explicit opt-in for "this scan target was never meant to
+    // represent a real page" -- see helpers.isWholeDocumentScope().
+    const fragment = !!(engineOptionsResolved && engineOptionsResolved.fragment === true);
 
     const url = pageUrl || (document.location && document.location.href) || null;
     const title = document.title || null;
@@ -61,6 +64,21 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
             ? engineOptionsResolved.timestamp.trim()
             : null;
 
+    // createDomHelpers()/createContrastHelpers() persist their element-keyed
+    // caches (outerHtmlCache, selectorCache, etc.) on window.__a11ycoreSharedCache
+    // so multiple helper instances created *within this run* can share them
+    // deterministically. But a window/document is frequently reused across
+    // SEPARATE runs -- e.g. Jest's jsdom environment creates one window per
+    // test file, and mutating document.body between it() blocks is standard.
+    // Those caches are keyed by element reference, not content, so a run that
+    // reuses an already-cached element (document.body never changes identity)
+    // would otherwise read stale data cached by an earlier, unrelated run on
+    // the same window. Clearing at the start of every run keeps sharing scoped
+    // to "this run" as intended, without leaking across runs.
+    try {
+        if (window && window.__a11ycoreSharedCache) window.__a11ycoreSharedCache = {};
+    } catch {}
+
     const sharedHelpers = createDomHelpers({
         document,
         window,
@@ -68,6 +86,7 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
         includeShadowDom,
         includeHiddenElements,
         excludeSelectors,
+        fragment,
         // Optional perf counters (bench/debug only). Deterministic and per-run.
         perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)
     });
@@ -204,6 +223,8 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
                 ruleVersion: normalizedMeta.ruleVersion,
                 normative: normalizedMeta.normative,
                 atomic: normalizedMeta.atomic,
+                deprecated: normalizedMeta.deprecated,
+                deprecation: normalizedMeta.deprecation,
                 category: normalizedMeta.category,
                 standard: normalizedMeta.standard,
                 applicability: normalizedMeta.applicability,
@@ -463,6 +484,8 @@ function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, R
                 ruleVersion: '0.0.0',
                 normative: true,
                 atomic: false,
+                deprecated: false,
+                deprecation: null,
                 category: null,
                 standard: null,
                 applicability: '',

package/src/core/rule-meta.js

@@ -80,6 +80,23 @@ function normalizeRuleMeta(ruleId, id, meta, engineTag) {
   const normative = (typeof m.normative === 'boolean') ? m.normative : true;
   const atomic = (typeof m.atomic === 'boolean') ? m.atomic : true;
 
+  // Deprecation signal for the rule catalog (see docs/API_STABILITY.md).
+  // Purely informational -- a deprecated rule still runs and produces
+  // results completely normally; this is a catalog-level migration signal
+  // for integrators, not an automatic exclusion.
+  const deprecated = (typeof m.deprecated === 'boolean') ? m.deprecated : false;
+  const deprecation = (deprecated && m.deprecation && typeof m.deprecation === 'object' && !Array.isArray(m.deprecation))
+      ? {
+          replacedBy: (typeof m.deprecation.replacedBy === 'string' && m.deprecation.replacedBy.trim()) ? m.deprecation.replacedBy.trim() : null,
+          reason: (typeof m.deprecation.reason === 'string') ? m.deprecation.reason.trim() : '',
+          sinceVersion: (typeof m.deprecation.sinceVersion === 'string') ? m.deprecation.sinceVersion.trim() : ''
+        }
+      : null;
+
+  if (deprecated && (!deprecation || !deprecation.reason || !deprecation.sinceVersion)) {
+    throw new Error(`Rule ${ruleId}: meta.deprecated:true requires meta.deprecation.reason and meta.deprecation.sinceVersion`);
+  }
+
   const category = (typeof m.category === 'string' && m.category.trim()) ? m.category.trim() : null;
   const standard = (typeof m.standard === 'string' && m.standard.trim()) ? m.standard.trim() : null;
 
@@ -127,6 +144,8 @@ function normalizeRuleMeta(ruleId, id, meta, engineTag) {
     ruleVersion,
     normative,
     atomic,
+    deprecated,
+    deprecation,
     category,
     standard,
     applicability,