@surea11y/core 1.5.0 → 1.7.0

package/src/checks/manual/link-name-quality-manual.js

@@ -9,29 +9,38 @@
  * @standard WCAG 2.2
  * @sc 2.4.4
  * @applicability
- *   Elements matching `a[href]` with a non-empty computed accessible
- *   name (programmatic first, then "name from content" — same
- *   two-step resolution as `link-name-present`). Links with no name at
- *   all are `link-name-present`'s concern, not this rule's.
+ *   Elements matching `a[href], area[href], [role="link"]` with a
+ *   non-empty computed accessible name (programmatic first, then "name
+ *   from content", same two-step resolution as `link-name-present`,
+ *   same selector too). Links with no name at all are
+ *   `link-name-present`'s concern, not this rule's.
  * @expectation
  *   The link's full accessible name, normalized (trimmed, case-folded,
  *   trailing punctuation stripped), is not an exact match for a known
  *   non-descriptive phrase ("click here", "read more", "more", "here",
- *   "details", "link", etc.) — WCAG technique F84's known failure
- *   pattern for SC 2.4.4.
+ *   "details", "link", etc., WCAG technique F84's known failure pattern
+ *   for SC 2.4.4) or a bare file-format/type name ("HTML", "PDF", "EPUB",
+ *   ...) with no adjacent context (an aria-describedby target, the
+ *   enclosing list item/table cell/paragraph's own text, or (format
+ *   names only) a table's first-row header) naming what it belongs to.
  * @implementation-notes
- * - Deliberately EXACT match only, against a small, well-established
- *   phrase list — not a substring/contains check. "Read more about our
+ * - EXACT match only, on purpose, against small, well-established
+ *   phrase lists, not a substring/contains check. "Read more about our
  *   privacy policy" does not match "read more"; only the bare phrase
  *   alone does. This keeps false positives near zero at the cost of
  *   not catching every possible non-descriptive phrasing (e.g. "click
- *   this", a legitimate but uncommon variant, is not in the list).
- * - Authored as `type: 'manual'` (cantTell-capped, never fail): this
- *   check does not verify whether *surrounding context* (adjacent text,
- *   aria-describedby) makes the purpose clear, which is exactly what
- *   distinguishes a genuine 2.4.4 failure (context doesn't help) from
- *   a link that's fine in context despite generic-sounding text alone.
- *   Flagging is a signal for review, not a definitive violation.
+ *   this", a legitimate but uncommon variant, is not in either list).
+ * - Adjacent-context detection climbs through a bare wrapping list into
+ *   an outer list item, so "Ulysses" heading a list of per-format
+ *   download links still counts as that list's context. The table-header
+ *   signal is format-name-only: a header cell can be present and still
+ *   say nothing about what a generic "Download" link in the same row
+ *   leads to, so the boilerplate-phrase list doesn't get that credit.
+ * - Still `type: 'manual'` (cantTell-capped, never fail): finding no
+ *   adjacent context is a strong signal, not proof that context doesn't
+ *   exist elsewhere (a preceding heading several rows up, page-level
+ *   framing) or that the surrounding text actually disambiguates.
+ *   Flagging is for review, not a definitive violation.
  * - Reuses the same accessible-name computation as `link-name-present`
  *   (`getAccessibleNameInfo` then `getContentNameInfo` as fallback), so
  *   this benefits from the same "name from content" recursion fix
@@ -43,7 +52,7 @@ const id = 'link-name-quality';
 const meta = {
   title: 'Link text should be descriptive, not generic',
   description:
-    'Flags links whose full accessible name is a known non-descriptive phrase (e.g. "click here", "read more", "more"), for manual review of whether the purpose is clear without additional context.',
+    'Flags links whose full accessible name is a known non-descriptive phrase (e.g. "click here", "read more", "more") or a bare file-format name (e.g. "HTML", "PDF") with no adjacent context naming what it leads to, for manual review of whether the purpose is clear.',
   i18n: {
     titleKey: 'linkNameQuality_title',
     descriptionKey: 'linkNameQuality_description'
@@ -92,6 +101,29 @@ function runInPage(ctx) {
     'info'
   ]);
 
+  const FORMAT_NAME_LINK_TEXT = new Set([
+    'html',
+    'pdf',
+    'epub',
+    'txt',
+    'plain text',
+    'doc',
+    'docx',
+    'xml',
+    'zip',
+    'mp3',
+    'mp4',
+    'csv',
+    'xls',
+    'xlsx',
+    'ppt',
+    'pptx',
+    'json',
+    'rtf'
+  ]);
+
+  const CONTEXT_BLOCK_TAGS = new Set(['td', 'th', 'p', 'dd', 'blockquote', 'figcaption', 'dt']);
+
   function normalize(s) {
     return (s == null ? '' : String(s))
       .replace(/\s+/g, ' ')
@@ -101,7 +133,84 @@ function runInPage(ctx) {
       .trim();
   }
 
-  const selector = 'a[href]';
+  function ownDirectText(el) {
+    let out = '';
+    const kids = el.childNodes || [];
+    for (let i = 0; i < kids.length; i++) {
+      const n = kids[i];
+      if (n.nodeType === 3) out += n.nodeValue || '';
+    }
+    return out.replace(/\s+/g, ' ').trim();
+  }
+
+  function isSubstantiveContext(text) {
+    return !!text && text.length >= 3 && /\p{L}/u.test(text);
+  }
+
+  // Direct text of the nearest enclosing list item/table cell/paragraph,
+  // climbing through a wrapping <ul>/<ol> into an outer <li> when the
+  // immediate one carries none of its own (a heading li wrapping a
+  // nested list of links, e.g. "Ulysses" above per-format download
+  // links).
+  function nearestBlockContextText(el) {
+    let node = el.parentElement;
+    let liHops = 0;
+    while (node) {
+      const tag = (node.tagName || '').toLowerCase();
+      if (tag === 'li') {
+        const text = ownDirectText(node);
+        if (text) return text;
+        liHops += 1;
+        if (liHops >= 4) return '';
+        const list = node.parentElement;
+        node = list ? list.parentElement : null;
+        continue;
+      }
+      if (CONTEXT_BLOCK_TAGS.has(tag)) return ownDirectText(node);
+      return '';
+    }
+    return '';
+  }
+
+  function describedByContextText(el) {
+    const describedBy = el.getAttribute ? el.getAttribute('aria-describedby') : null;
+    if (!describedBy || !describedBy.trim() || !helpers.getTextFromIdRefs) return '';
+    try {
+      const info = helpers.getTextFromIdRefs(describedBy, ctx);
+      return info && info.text ? info.text.replace(/\s+/g, ' ').trim() : '';
+    } catch {
+      return '';
+    }
+  }
+
+  // A table's first-row header text, when the link sits in a later row of
+  // the same table -- naming the row's subject is exactly what turns a
+  // bare format name ("HTML") into a link whose destination is clear.
+  function firstRowHeaderText(el) {
+    const cell = el.closest ? el.closest('td, th') : null;
+    if (!cell) return '';
+    const table = cell.closest ? cell.closest('table') : null;
+    if (!table || !table.rows || !table.rows.length) return '';
+    const headerRow = table.rows[0];
+    const cellRow = cell.closest ? cell.closest('tr') : null;
+    if (!cellRow || headerRow === cellRow) return '';
+    const ths = headerRow.querySelectorAll ? headerRow.querySelectorAll('th') : [];
+    if (!ths.length) return '';
+    return Array.prototype.map
+      .call(ths, (th) => th.textContent || '')
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  function hasAdequateContext(el, tier) {
+    if (isSubstantiveContext(describedByContextText(el))) return true;
+    if (isSubstantiveContext(nearestBlockContextText(el))) return true;
+    if (tier === 'format' && isSubstantiveContext(firstRowHeaderText(el))) return true;
+    return false;
+  }
+
+  const selector = 'a[href], area[href], [role="link"]';
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);
@@ -131,27 +240,47 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    if (!GENERIC_LINK_TEXT.has(normalized)) continue;
+    const isGeneric = GENERIC_LINK_TEXT.has(normalized);
+    const isFormatName = !isGeneric && FORMAT_NAME_LINK_TEXT.has(normalized);
+    if (!isGeneric && !isFormatName) continue;
+
+    const tier = isGeneric ? 'generic' : 'format';
+    if (hasAdequateContext(el, tier)) continue;
 
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
       : null;
 
-    occurrences.push(
-      helpers.reportOccurrence(el, {
-        summary: `This link's accessible name ("${rawName.trim()}") is a generic, non-descriptive phrase.`,
-        hint: 'Make the link text itself describe its destination/purpose (e.g. "Download the 2026 pricing guide" instead of "Download"), or confirm the surrounding context already makes the purpose clear.',
-        i18n: {
-          summaryKey: 'linkNameQuality_summary_cantTell',
-          hintKey: 'linkNameQuality_hint_cantTell',
-          params: { name: rawName.trim() }
-        },
-        data: {
-          details: { reasonCode: 'GENERIC_LINK_TEXT', normalizedName: normalized },
-          visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+    const name = rawName.trim();
+    const reportOpts = isGeneric
+      ? {
+          summary: `This link's accessible name ("${name}") is a generic, non-descriptive phrase.`,
+          hint: 'Make the link text itself describe its destination/purpose (e.g. "Download the 2026 pricing guide" instead of "Download"), or confirm the surrounding context already makes the purpose clear.',
+          i18n: {
+            summaryKey: 'linkNameQuality_summary_cantTell',
+            hintKey: 'linkNameQuality_hint_cantTell',
+            params: { name }
+          },
+          data: {
+            details: { reasonCode: 'GENERIC_LINK_TEXT', normalizedName: normalized },
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+          }
         }
-      })
-    );
+      : {
+          summary: `This link's accessible name ("${name}") names a file format/type but not the document it belongs to.`,
+          hint: 'Name the document in the link text or in nearby text/a heading the link is associated with (e.g. "Download the annual report (HTML)" instead of a bare "HTML").',
+          i18n: {
+            summaryKey: 'linkNameQuality_summary_cantTell_formatName',
+            hintKey: 'linkNameQuality_hint_cantTell_formatName',
+            params: { name }
+          },
+          data: {
+            details: { reasonCode: 'AMBIGUOUS_FORMAT_NAME', normalizedName: normalized },
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+          }
+        };
+
+    occurrences.push(helpers.reportOccurrence(el, reportOpts));
   }
 
   if (applicableCount === 0) {

package/src/checks/manual/media-transcript-present-manual.js

@@ -18,10 +18,9 @@
 const id = 'media-alternative-transcript-evidence';
 
 const meta = {
-  title: 'Time-based media: transcript / media alternative evidence',
+  title: 'Time-based media: transcript or text alternative evidence',
   description:
-    'Finds <audio>/<video> elements where a transcript or other text alternative is not strongly evidenced in-page. ' +
-    'This rule is conservative and returns cantTell when evidence is missing or unverified.',
+    'Finds audio and video elements where a transcript or other text alternative is not strongly evidenced in the page content. This rule is conservative and reports cantTell when evidence is missing or cannot be verified.',
   i18n: {
     titleKey: 'mediaTranscriptPresent_title',
     descriptionKey: 'mediaTranscriptPresent_description'

package/src/checks/manual/meta-viewport-large-manual.js

@@ -6,7 +6,7 @@
  * @check meta-viewport-large
  * @atomic true
  * @summary Viewport meta tag should allow zooming up to 500% (AAA-level)
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to <meta name="viewport"> elements that carry a non-empty
  *   content attribute.
@@ -17,7 +17,7 @@
  *   enforces the AA 200% minimum as a hard, WCAG-normative fail); this
  *   rule is advisory best-practice guidance toward the higher AAA bar.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - Distinct, atomic decision from meta-viewport-zoom-enabled

package/src/checks/manual/mouse-only-event-handlers-manual.js

@@ -18,31 +18,31 @@
  *   The element also carries at least one keyboard-reachable inline
  *   handler: `onkeydown`, `onkeyup`, `onkeypress` (the direct keyboard-
  *   event equivalents), or `onfocus`/`onblur` (the standard substitute
- *   for hover-triggered behavior — focus/blur are the keyboard-
+ *   for hover-triggered behavior: focus/blur are the keyboard-
  *   navigable analog to mouseover/mouseout, per WCAG technique G90).
  *   Otherwise the element's mouse-driven behavior (a hover tooltip, a
  *   custom dropdown, a drag interaction) has no way to be triggered by a
  *   keyboard-only user.
  * @implementation-notes
  * - Authored as `type: 'manual'` (cantTell-capped, never fail), not
- *   `automatic`: this can only see inline `on*="..."` HTML attributes —
- *   a keyboard handler attached elsewhere via `addEventListener` (the
+ *   `automatic`: this can only see inline `on*="..."` HTML attributes.
+ *   A keyboard handler attached elsewhere via `addEventListener` (the
  *   norm in most modern frameworks) is invisible to a static markup
  *   scan and would make a `fail` a false positive. Surfaced by a diff
- *   against a legacy ruleset's WCAG2AA rules (see ROADMAP.md's Tier 4
- *   research notes) — this is a real, well-known WCAG 2.1.1 anti-pattern
+ *   against a legacy ruleset's WCAG2AA rules; this is a real, well-known
+ *   WCAG 2.1.1 anti-pattern
  *   (technique G90/F54) that nothing else in this rule set checks.
- * - Deliberately does NOT treat `onclick` as a keyboard-equivalent
- *   excuse: whether `onclick` is keyboard-reachable depends on the
+ * - Does NOT treat `onclick` as a keyboard-equivalent excuse on purpose:
+ *   whether `onclick` is keyboard-reachable depends on the
  *   element's separate focusability (native interactive tag or
- *   `tabindex`), which this rule does not attempt to cross-check — and
+ *   `tabindex`), which this rule does not attempt to cross-check, and
  *   for the specific hover-triggered handlers this rule targets
  *   (`onmouseover`/`onmouseout`/etc.), `onclick` isn't actually an
  *   equivalent interaction model regardless of focusability (hover and
  *   click are different gestures with different semantics).
  * - Only inline HTML attribute handlers are detectable; JS-attached
  *   listeners (`addEventListener('mouseover', ...)`) are invisible to a
- *   static DOM scan — a documented limitation, not an oversight.
+ *   static DOM scan. That's a documented limitation, not an oversight.
  */
 
 const id = 'mouse-only-event-handlers';

package/src/checks/manual/no-autoplay-audio-manual.js

@@ -14,8 +14,8 @@
  *   SC 1.4.2 only applies when audio plays automatically for MORE than 3
  *   seconds; clip duration is not knowable from static markup (jsdom does
  *   not decode media), so this rule cannot determine whether the SC even
- *   applies to a given element. It is deliberately authored as `type:
- *   'manual'` (cantTell-capped, never fail) rather than guessing: an
+ *   applies to a given element. It is authored as `type:
+ *   'manual'` (cantTell-capped, never fail) on purpose rather than guessing: an
  *   autoplaying unmuted element with no `controls` attribute (the native,
  *   statically-verifiable mechanism to pause/stop or adjust volume) is
  *   flagged for human review rather than treated as a deterministic
@@ -28,7 +28,7 @@
  *   audible, so the SC's condition ("plays automatically... audio")
  *   does not apply.
  * - Custom (JS-built) controls that don't use the native `controls`
- *   attribute cannot be detected statically — a documented limitation,
+ *   attribute cannot be detected statically. That's a documented limitation,
  *   same class as `iframe-focusable-content`'s `contentDocument` gap.
  * - Not gated on `isAccTreeEligible`: unlike most rules, a `display:none`
  *   or `aria-hidden` audio/video element still plays audible sound in a

package/src/checks/manual/object-text-alternative-quality-manual.js

@@ -9,6 +9,14 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to <object> elements that already carry a text alternative:
+ *   fallback text content, a non-empty aria-label, an aria-labelledby that
+ *   resolves to non-empty text, or a non-empty title. An <object> with none
+ *   of those is object-text-alternative-present's failure, not a quality
+ *   question. The element must be included in the accessibility tree, and
+ *   role="presentation"/"none" takes it out of scope unless it is focusable,
+ *   which restores its role.
  * @expectation
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */

package/src/checks/manual/p-as-heading-manual.js

@@ -17,18 +17,18 @@
  *   Text styled to visually read as a heading (bold, larger-than-body
  *   size, short) should be marked up with a real heading element
  *   (`<h1>`-`<h6>` or `role="heading"`) so its structural role is
- *   programmatically determinable — the same 1.3.1 concern as any other
+ *   programmatically determinable, the same 1.3.1 concern as any other
  *   "structure conveyed through presentation only" issue.
  * @implementation-notes
  * - This is a stylistic heuristic (bold + large + short), not a
- *   deterministic structural check — a short bold sentence is not
+ *   deterministic structural check: a short bold sentence is not
  *   necessarily wrong as a `<p>`. Authored as `type: 'manual'`
  *   (cantTell-capped, never fail) to avoid false-flagging legitimate
  *   emphasis, matching this repo's other heuristic-heavy Tier 2/3
  *   rules (e.g. `scrollable-region-focusable`).
  * - Uses an absolute 18px size threshold rather than comparing against
- *   surrounding text (unlike `link-in-text-block`) — deliberately
- *   simpler, since "looks like a heading" is closer to an absolute
+ *   surrounding text (unlike `link-in-text-block`); it's simpler on
+ *   purpose, since "looks like a heading" is closer to an absolute
  *   judgment than a relative-contrast one.
  */
 

package/src/checks/manual/page-has-heading-one-manual.js

@@ -6,9 +6,9 @@
  * @check page-has-heading-one
  * @atomic true
  * @summary The page should have at least one level-one heading
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
- *   Always applicable to any HTML document with a <body> element —
+ *   Always applicable to any HTML document with a <body> element:
  *   "does the page have an h1" is a whole-page concern, matching
  *   bypass-blocks-present's pattern of evaluating the document
  *   directly.
@@ -18,18 +18,18 @@
  *   heading has no clear entry point for assistive technology users
  *   navigating by heading.
  * @implementation-notes
- * - Not WCAG-normative — authored as an advisory, cantTell-capped
+ * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
  * - Filters candidates through `isAccTreeEligible` (hidden/aria-hidden/
  *   display:none/inert elements don't count as "the page has a heading
- *   one"), matching `landmark-one-main`'s own precedent — a raw
+ *   one"), matching `landmark-one-main`'s own precedent. A raw
  *   `document.querySelectorAll` would wrongly credit an `<h1>` that sits
- *   inside a `display:none` ancestor, genuinely unreachable by sighted and
+ *   inside a `display:none` ancestor, unreachable by sighted and
  *   screen reader users alike, as satisfying this check. This does NOT
  *   regress purely-visually-clipped-but-AT-exposed headings (e.g. an `<h1>`
  *   hidden via clip-path/off-screen positioning, `visibility:visible`, no
- *   `aria-hidden`) — `isAccTreeEligible` only excludes elements actually
+ *   `aria-hidden`): `isAccTreeEligible` only excludes elements actually
  *   removed from the accessibility tree, not ones merely clipped from the
  *   visual viewport.
  */

package/src/checks/manual/page-title-patterns-manual.js

@@ -2,13 +2,36 @@
 
 'use strict';
 
+/**
+ * @check page-title-patterns
+ * @atomic true
+ * @summary Manual review: page titles that may not describe their page
+ * @standard WCAG 2.2
+ * @sc 2.4.2
+ * @applicability
+ *   Applies to a run over a whole document whose <title> resolves to
+ *   non-empty text; a missing or empty title is page-title-present's
+ *   failure, not a pattern to review. A run narrowed by contextSelector or
+ *   by engineOptions.fragment is notApplicable, as is a title matching none
+ *   of the patterns below.
+ * @expectation
+ *   The title carries none of the conservative low-descriptiveness signals:
+ *   one of the generic titles home, homepage, welcome, untitled, page or
+ *   document; fewer than eight characters; or a template shape pairing a
+ *   generic token with a brand, such as "Home | Brand". When the
+ *   crawl.pageTitles probe supplies at least ten pages, cross-page signals
+ *   are used instead: one title repeated across distinct URLs, or a prefix
+ *   or suffix of twelve characters or more shared across the set. Every
+ *   signal is reported as cantTell: whether a title describes its page is a
+ *   judgment, so the rule never fails on a pattern alone.
+ */
+
 const id = 'page-title-patterns';
 
 const meta = {
-  title: 'Page title patterns that may indicate low descriptiveness',
+  title: 'Page title patterns that may be insufficiently descriptive',
   description:
-    'Flags page titles that are likely too generic or templated as review signals (WCAG 2.2 SC 2.4.2). ' +
-    'This rule is conservative and does not fail based on patterns alone.',
+    'Identifies page title patterns that may indicate low descriptiveness, such as generic, duplicated, or overly templated titles. This rule provides review signals and does not fail automatically.',
   i18n: {
     titleKey: 'pageTitlePatterns_title',
     descriptionKey: 'pageTitlePatterns_description'