@surea11y/core 1.5.0 → 1.7.0

package/src/checks/manual/password-paste-enabled-manual.js

@@ -0,0 +1,255 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * @check password-paste-enabled
+ * @atomic true
+ * @summary An authentication field must not block pasting into it
+ * @standard WCAG 2.2
+ * @sc 3.3.8
+ * @applicability
+ *   Applies to any control whose autocomplete token is current-password,
+ *   new-password or one-time-code, and to <input type="password"> unless its
+ *   autocomplete names another purpose. A disabled or readonly field takes no
+ *   input to block, and one outside the accessibility tree is not being asked
+ *   for, so neither is in scope.
+ * @expectation
+ *   A reviewer confirms the field can still be pasted into. Remembering a
+ *   password is a cognitive function test, and 3.3.8 asks for a mechanism
+ *   that helps the user through one; a password manager, or the clipboard
+ *   for a one-time code, is that mechanism.
+ * @implementation-notes
+ * - Advisory and capped at cantTell. Whether a handler really stops the user
+ *   depends on script the markup does not carry, so no reading of it is safe
+ *   enough to fail on: a split one-time-code field cancels the default paste
+ *   and then spreads the digits across its boxes. The two cases are reported
+ *   apart -- a handler that only cancels, and one that goes on to do more --
+ *   so a reviewer knows which to look at first. `return true` allows the
+ *   paste and reports nothing.
+ * - type="password" masks rather than authenticates, and a card security code
+ *   is masked the same way, so an autocomplete naming another purpose puts the
+ *   field out of scope. A masked field with no autocomplete cannot be told
+ *   apart, which is the one case left.
+ * - `autocomplete="off"` is not reported. Browsers override it for password
+ *   fields so password managers keep working, and the mechanism survives.
+ * - A handler attached with addEventListener leaves nothing to read, the
+ *   limit every static scan shares.
+ * - 3.3.8 also excuses the test where the process offers another
+ *   authentication method. A sibling button proves nothing about whether it
+ *   works or replaces this step, so it is not inferred; the facet is recorded
+ *   as partial for that reason.
+ */
+
+const id = 'password-paste-enabled';
+
+const meta = {
+  title: 'Authentication fields must not block pasting',
+  description:
+    'Checks that a password or one-time-code field carries no inline paste handler that cancels the paste, which would remove the password manager or clipboard that WCAG 3.3.8 relies on as the assisting mechanism.',
+  i18n: {
+    titleKey: 'passwordPasteEnabled_title',
+    descriptionKey: 'passwordPasteEnabled_description'
+  },
+  helpUrl: null,
+  tags: ['wcag22aa', 'wcag338', 'forms', 'authentication', 'atomic', 'manual', 'acc'],
+  wcagSc: ['3.3.8'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '3.3.8',
+      title: 'Accessible Authentication (Minimum)',
+      conformanceLevel: 'AA'
+    }
+  ],
+  defaultSeverity: 'serious',
+  category: 'understandable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: { facetsBySc: { '3.3.8': ['authentication-paste-not-blocked'] } }
+};
+
+function runInPage(ctx) {
+  const { helpers, rule } = ctx;
+
+  // Declared inside runInPage; see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  const AUTH_AUTOCOMPLETE_TOKENS = ['current-password', 'new-password', 'one-time-code'];
+
+  function normalizeWs(s) {
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  function autocompleteTokens(el) {
+    return normalizeWs(el.getAttribute && el.getAttribute('autocomplete'))
+      .toLowerCase()
+      .split(' ')
+      .filter(Boolean);
+  }
+
+  // A field an authentication step reads: a password input, or any control
+  // whose autocomplete token names an authentication secret. The autocomplete
+  // route matters for one-time codes, which are ordinary text inputs.
+  //
+  // type="password" is a masking control, not only an authentication one: a
+  // card security code is routinely masked the same way. An explicit
+  // autocomplete purpose that is not an authentication one says so, and takes
+  // the field back out of scope.
+  function isAuthField(el) {
+    const tag = el.tagName ? el.tagName.toLowerCase() : '';
+    if (tag !== 'input' && tag !== 'textarea') return false;
+
+    const tokens = autocompleteTokens(el);
+    if (AUTH_AUTOCOMPLETE_TOKENS.some((t) => tokens.includes(t))) return true;
+
+    const type = normalizeWs(el.getAttribute && el.getAttribute('type')).toLowerCase();
+    if (tag !== 'input' || type !== 'password') return false;
+
+    const declaresOtherPurpose = tokens.some(
+      (t) => t !== 'on' && t !== 'off' && !AUTH_AUTOCOMPLETE_TOKENS.includes(t)
+    );
+    return !declaresOtherPurpose;
+  }
+
+  // A field that takes no input at all cannot be pasted into either, so a
+  // paste handler on it blocks nothing.
+  function acceptsInput(el) {
+    if (el.hasAttribute && (el.hasAttribute('disabled') || el.hasAttribute('readonly'))) {
+      return false;
+    }
+    return true;
+  }
+
+  // Classifies an inline handler as 'cancelOnly', 'opaque' or 'none'.
+  //
+  // Cancelling is not the same as blocking. Replacing the default paste is
+  // how a split one-time-code field distributes the digits across its boxes,
+  // and how a password field strips stray whitespace from what was pasted --
+  // both call preventDefault and then insert the text themselves, which
+  // helps the user rather than stopping them. So a handler counts as
+  // blocking only when cancelling is the whole of what it does. Anything
+  // further -- a call, an assignment, a condition -- may well be putting the
+  // text back, and the markup does not say, so it reports cantTell.
+  function classifyHandler(source) {
+    const src = String(source || '').trim();
+    if (!src) return 'none';
+
+    const CANCEL = [
+      /\breturn\s+false\b/gi,
+      /\breturn\s*!1\b/gi,
+      /\bpreventDefault\s*\(\s*\)/gi,
+      /\breturnValue\s*=\s*(?:false|!1)\b/gi
+    ];
+    // Says "yes, paste" outright, so it blocks nothing.
+    const ALLOW = [/\breturn\s+true\b/gi, /\breturn\s*!0\b/gi];
+    // Neither cancels nor re-inserts.
+    const NEUTRAL = [/\bstop(?:Immediate)?Propagation\s*\(\s*\)/gi, /\breturn\b/gi];
+    // What is left of an object reference once its method call is removed.
+    const REFS = /\b(?:window|document|this|event|evt|ev|e|arguments\[0\])\b/gi;
+    const ONLY_PUNCTUATION = /^[\s;.,()[\]{}]*$/;
+
+    let rest = src;
+    let sawCancel = false;
+    for (const re of CANCEL) {
+      const next = rest.replace(re, ' ');
+      if (next !== rest) sawCancel = true;
+      rest = next;
+    }
+
+    if (!sawCancel) {
+      for (const re of ALLOW) rest = rest.replace(re, ' ');
+      for (const re of NEUTRAL) rest = rest.replace(re, ' ');
+      rest = rest.replace(REFS, ' ');
+      return ONLY_PUNCTUATION.test(rest) ? 'none' : 'opaque';
+    }
+
+    for (const re of NEUTRAL) rest = rest.replace(re, ' ');
+    rest = rest.replace(REFS, ' ');
+    // Anything left beyond punctuation is the handler doing more than cancel.
+    return ONLY_PUNCTUATION.test(rest) ? 'cancelOnly' : 'opaque';
+  }
+
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('input, textarea')
+    : helpers.queryAll('input, textarea');
+
+  const cancelling = [];
+  const undetermined = [];
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    if (!isAuthField(el)) continue;
+
+    if (!acceptsInput(el)) continue;
+
+    const eligResult = helpers.isAccTreeEligible ? helpers.isAccTreeEligible(el, ctx) : true;
+    const eligible =
+      typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
+    if (!eligible) continue;
+
+    const handler = el.getAttribute('onpaste');
+    if (handler === null) continue;
+
+    const verdict = classifyHandler(handler);
+    if (verdict === 'none') continue;
+
+    const eligInfo = helpers.getEligibilityInfo
+      ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
+      : { targetSet: 'acc', accEligible: null, reasons: [] };
+
+    if (verdict === 'cancelOnly') {
+      cancelling.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This authentication field has a paste handler whose only effect is to cancel the paste.',
+          hint: 'Confirm by hand whether pasting still works. If it is blocked, remove the handler so a password manager, or the clipboard for a one-time code, can fill the field.',
+          i18n: {
+            summaryKey: 'passwordPasteEnabled_summary_fail',
+            hintKey: 'passwordPasteEnabled_hint_fail',
+            params: {}
+          },
+          data: {
+            visibilityFilter: eligInfo,
+            details: { reasonCode: 'PASTE_CANCELLED', handler: normalizeWs(handler) }
+          }
+        })
+      );
+      continue;
+    }
+
+    // An inline handler that delegates: whether it cancels lives in code the
+    // markup does not carry.
+    undetermined.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This authentication field has a paste handler, and whether it cancels pasting could not be determined.',
+        hint: 'Check by hand that pasting into the field still works, so a password manager or the clipboard can fill it.',
+        i18n: {
+          summaryKey: 'passwordPasteEnabled_summary_cantTell',
+          hintKey: 'passwordPasteEnabled_hint_cantTell',
+          params: {}
+        },
+        data: {
+          visibilityFilter: eligInfo,
+          details: { reasonCode: 'PASTE_HANDLER_OPAQUE', handler: normalizeWs(handler) }
+        }
+      })
+    );
+  }
+
+  const occurrences = cancelling.concat(undetermined);
+  if (!occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'cantTell',
+    severity: rule.defaultSeverity || 'serious',
+    occurrences
+  };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/presentation-role-conflict-manual.js

@@ -6,28 +6,29 @@
  * @check presentation-role-conflict
  * @atomic true
  * @summary role="presentation"/"none" must not be combined with a global ARIA naming attribute or focusability
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with an explicit role="presentation" or
- *   role="none", OR an <img alt=""> (empty alt gives an <img> an implicit
- *   presentation role per HTML-AAM, even with no explicit role attribute
- *   at all — `img[alt=''], [role="none"], [role="presentation"]`).
+ *   role="none", OR an <img alt=""> carrying no explicit role of its own
+ *   (empty alt gives an <img> an implicit presentation role per HTML-AAM,
+ *   even with no explicit role attribute at all: `img[alt=''],
+ *   [role="none"], [role="presentation"]`).
  * @expectation
  *   The element does not also carry a WAI-ARIA *global* state/property
  *   (aria-label, aria-hidden, aria-describedby, aria-live, aria-current,
- *   ... — the full global-attribute set, not just the naming ones), AND
+ *   ...; the full global-attribute set, not just the naming ones), AND
  *   is not focusable. Per the WAI-ARIA spec's Presentational Roles
  *   Conflict Resolution section, a presentational role is "restored" to
- *   the element's implicit semantic role when either condition holds —
+ *   the element's implicit semantic role when either condition holds:
  *   the presentation/none role silently stops working, contradicting the
  *   author's evident intent to hide the element from the accessibility
  *   tree.
  * @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.
  * - `aria-hidden="true"` (the exact valid truthy value) on the
- *   presentational element itself is deliberately EXCLUDED as a trigger,
+ *   presentational element itself is EXCLUDED as a trigger on purpose,
  *   even though it's a global ARIA attribute: it removes the element from
  *   the accessibility tree unconditionally, so the "role restoration"
  *   this rule warns about never actually reaches assistive tech, making a
@@ -38,18 +39,23 @@
  *   exemption (see the code comment at the check site).
  * - The conflicting-attribute set is the full list of ARIA attributes
  *   marked `global: true`, not a narrower naming-only list.
- * - Deliberately NOT applying an implicit-role applicability gate that
+ * - Not applying an implicit-role applicability gate on purpose, one that
  *   would make the check inapplicable to role="presentation" on elements
  *   with no native implicit role to suppress (e.g. `<div
- *   role="presentation" aria-hidden="true">` — a <div> has no native role,
+ *   role="presentation" aria-hidden="true">`: a <div> has no native role,
  *   so there's nothing for the presentational role to "conflict" with).
  *   surea11y stays broader/more cautious here rather than narrower, which
- *   is the safer direction to diverge in. The native-implicit-role table
- *   needed to add that gate, if this scope decision is ever revisited, is
- *   in ROADMAP.md §7 item 9.
+ *   is the safer direction to diverge in. Adding that gate later would
+ *   need a native-implicit-role table, which doesn't exist yet.
  * - Focusability is computed via helpers.getFocusableInfo (native +
- *   tabindex), same helper aria-hidden-focus already relies on — a
+ *   tabindex), same helper aria-hidden-focus already relies on. A
  *   `:disabled` or otherwise non-focusable element is not flagged.
+ * - An `<img alt="">` carrying an explicit role of its own (e.g. `<img
+ *   alt="" role="img" aria-label="Logo">`) is out of scope: the explicit
+ *   role wins over the presentation role empty alt would otherwise confer,
+ *   so nothing presentational is left to conflict with. An explicit role
+ *   whose tokens are all unknown confers nothing either, and the empty alt
+ *   still applies.
  */
 
 const id = 'presentation-role-conflict';
@@ -77,7 +83,7 @@ function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
   // The full set of ARIA attributes marked `global: true` per the WAI-ARIA
-  // spec — any of these present on a presentational element restores its
+  // spec. Any of these present on a presentational element restores its
   // implicit role, not just the naming ones.
   const CONFLICTING_ATTRS = [
     'aria-atomic',
@@ -109,6 +115,26 @@ function runInPage(ctx) {
   const getFocusableInfo =
     helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
 
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+
+  // The role attribute holds a fallback list; the first token naming a real
+  // role wins, and unknown tokens are skipped over. Returns '' when the
+  // element has no role attribute or none of its tokens name a role: the
+  // cases where an <img alt=""> keeps the presentation role empty alt gives
+  // it.
+  function getEffectiveRoleToken(el) {
+    const raw = el.getAttribute ? el.getAttribute('role') : null;
+    if (!raw) return '';
+    const tokens = String(raw).trim().toLowerCase().split(/\s+/);
+    for (const token of tokens) {
+      if (!token) continue;
+      if (token === 'presentation' || token === 'none') return token;
+      const known = ariaHelpers ? ariaHelpers.isValidConcreteRole(token) : true;
+      if (known) return token;
+    }
+    return '';
+  }
+
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('[role="presentation"], [role="none"], img[alt=""]')
     : helpers.queryAll('[role="presentation"], [role="none"], img[alt=""]');
@@ -119,30 +145,37 @@ function runInPage(ctx) {
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
 
+    // Only reachable via the img[alt=""] branch of the selector: an explicit
+    // role other than presentation/none overrides the presentation role that
+    // empty alt would confer, leaving no presentational intent to conflict
+    // with.
+    const roleToken = getEffectiveRoleToken(el);
+    if (roleToken && roleToken !== 'presentation' && roleToken !== 'none') continue;
+
     applicableCount += 1;
 
     // Presence, not value truthiness: the WAI-ARIA role-conflict-resolution
     // rule triggers on a global ARIA attribute being SPECIFIED at all, even
-    // with an empty value — e.g. <img alt="" aria-hidden="">, where
+    // with an empty value, e.g. <img alt="" aria-hidden="">, where
     // aria-hidden="" (empty string) is still a specified attribute. A
     // truthy-value check would miss this.
     let present = CONFLICTING_ATTRS.filter((attr) =>
       el.hasAttribute ? el.hasAttribute(attr) : el.getAttribute(attr) != null
     );
 
-    // aria-hidden="true" (the exact, valid truthy value — not the
+    // aria-hidden="true" (the exact, valid truthy value, not the
     // empty-string case above, which never actually hides anything) is a
     // special case: it removes the element and its subtree from the
     // accessibility tree unconditionally, independent of role. That makes
     // the "role restoration" this rule warns about ("...which restores its
     // implicit role and cancels the presentational intent") factually
-    // inert — no AT will ever expose the restored role OR any of the other
+    // inert. No AT will ever expose the restored role OR any of the other
     // conflicting attributes (aria-label, aria-describedby, ...) present
     // alongside it, since the whole element stays out of the tree
     // regardless. This pattern is extremely common (e.g. <svg
-    // role="presentation" aria-hidden="true"> decorative icons — a
+    // role="presentation" aria-hidden="true"> decorative icons, a
     // defensive belt-and-suspenders double-hide, not an authoring mistake).
-    // Focusability is NOT covered by this exemption — a keyboard user can
+    // Focusability is NOT covered by this exemption: a keyboard user can
     // still tab onto an aria-hidden="true" focusable element (the
     // aria-hidden-focus anti-pattern), a real, independent hazard
     // aria-hidden does nothing to prevent.
@@ -165,12 +198,9 @@ function runInPage(ctx) {
     const parts = present.slice();
     if (isFocusable) parts.push('focusable');
 
-    // No explicit role attribute means this matched via the img[alt=""]
+    // No role token means this matched via the img[alt=""]
     // implicit-presentation case.
-    const role =
-      String(el.getAttribute('role') || '')
-        .trim()
-        .toLowerCase() || 'presentation';
+    const role = roleToken || 'presentation';
 
     occurrences.push(
       helpers.reportOccurrence(el, {

package/src/checks/manual/region-manual.js

@@ -6,10 +6,10 @@
  * @check region
  * @atomic true
  * @summary Page content should be contained within a landmark region
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to any element under <body> that directly carries visible text
- *   (or other own content — see @implementation-notes) and is not itself a
+ *   (or other own content, see @implementation-notes) and is not itself a
  *   landmark, live region, dialog, button, <svg>, <iframe>/<frame>, or a
  *   resolvable skip-link.
  * @expectation
@@ -18,14 +18,14 @@
  *   search), so assistive technology users navigating by landmark do not
  *   miss content that was never placed inside one.
  * @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 and the landmark-
  *   detection model.
  * - Recursive tree walk, not a direct-<body>-children-only scan: a
  *   direct-children-only scope is nearly inert on the single most common
  *   real-world page shape, a modern framework's single root mount div
- *   (`<body><div id="root">...everything...</div></body>`) — that shape
+ *   (`<body><div id="root">...everything...</div></body>`). That shape
  *   gives at most one candidate for the entire page and either misses
  *   every real gap inside it or collapses the whole page into one
  *   undifferentiated report.
@@ -37,30 +37,30 @@
  *        live region, dialog, button, <svg>, <iframe>/<frame>, or a
  *        resolvable skip-link), mark it and every ancestor up to <body> as
  *        "has a stopper" and don't recurse further into it (an <iframe>/
- *        <frame> is additionally reported as its own occurrence — its
+ *        <frame> is additionally reported as its own occurrence, since its
  *        content is opaque to this engine, so from the outer page's
  *        perspective it IS unplaced content).
  *     3. Otherwise, if the node has OWN content (a direct child text node,
- *        being an inherently visual element, or an aria-label) — checked
- *        non-recursively, so a plain wrapper <div> with only nested
- *        children never short-circuits the walk into its descendants —
+ *        being an inherently visual element, or an aria-label), checked
+ *        non-recursively so a plain wrapper <div> with only nested
+ *        children never short-circuits the walk into its descendants,
  *        collect it as a candidate and stop recursing into it.
  *     4. Otherwise recurse into its element children.
  *   Each collected candidate is then walked back UP through parents while
  *   the parent has no "stopper" marker and isn't <body> itself, collapsing
  *   contiguous unplaced content into one occurrence per real gap instead
- *   of reporting every individual text-bearing leaf — this is what keeps
+ *   of reporting every individual text-bearing leaf. This is what keeps
  *   the walk from being noisy on ordinary pages that mix landmarked and
  *   stray content.
  * - "Stopper" exemptions (button, dialog, <svg>, resolvable skip-links)
- *   are a deliberate scope choice, not an oversight: these
+ *   are a scope choice, not an oversight: these
  *   are extremely common real-world patterns (floating action buttons,
  *   modal dialogs, decorative/icon SVGs, "skip to content" links) that
  *   aren't the kind of "content organization" gap this rule exists to
  *   catch, and flagging them would reintroduce the false-positive noise
  *   the original narrow scope was trying to avoid.
- * - The "own content" check for aria-label deliberately does NOT resolve
- *   aria-labelledby — a known, narrow scope gap (an element named only via aria-labelledby, with no
+ * - The "own content" check for aria-label does NOT resolve
+ *   aria-labelledby, a known, narrow scope gap (an element named only via aria-labelledby, with no
  *   own text/aria-label, and no other content anywhere in its subtree,
  *   could be silently skipped) accepted to avoid a full accessible-name
  *   computation (recursive itself) inside an already-recursive structural
@@ -137,11 +137,11 @@ function runInPage(ctx) {
 
   // Delegates to the shared helpers.hasLandmarkScopingAncestor for the
   // question "does this element sit inside a sectioning-content/<main>
-  // ancestor that suppresses its conditional implicit role" — role-aware
+  // ancestor that suppresses its conditional implicit role": role-aware
   // (an ancestor's bare TAG only counts when it carries no role attribute
   // at all; an explicit role="dialog"-style override no longer suppresses)
   // rather than a local tag-only copy. See that function's header comment
-  // in src/core/aria-helpers.js for the full algorithm — e.g. an
+  // in src/core/aria-helpers.js for the full algorithm, e.g. an
   // <aside role="dialog"> containing its own <header>, where the <header>
   // keeps its banner role.
   function hasSectioningAncestor(el, includeMain) {
@@ -189,7 +189,7 @@ function runInPage(ctx) {
   const SKIP_TAGS = new Set(['script', 'style', 'template', 'noscript', 'link', 'meta', 'title']);
 
   // Roles/attributes that make an element its own self-contained
-  // announced area — not literally a WAI-ARIA landmark, but not "content
+  // announced area: not literally a WAI-ARIA landmark, but not "content
   // that needs a landmark" either.
   const LIVE_REGION_ROLES = new Set(['alert', 'status', 'log', 'marquee', 'timer']);
 
@@ -217,8 +217,8 @@ function runInPage(ctx) {
     return false;
   }
 
-  // A "skip to content" link is deliberately placed outside the main
-  // content flow at the very top of the page — exempting it (when its
+  // A "skip to content" link is placed outside the main content flow
+  // on purpose, at the very top of the page. Exempting it (when its
   // fragment actually resolves to a real target, not a dead "#"
   // placeholder) avoids flagging a helpful, common accessibility pattern
   // as the very thing this rule is meant to catch.
@@ -249,8 +249,8 @@ function runInPage(ctx) {
 
   const VISUAL_CONTENT_TAGS = new Set(['img', 'video', 'audio', 'canvas', 'object', 'embed']);
 
-  // Non-recursive "does THIS element, on its own, carry content" check —
-  // deliberately mirrors only the direct-content half of getContentNameInfo,
+  // Non-recursive "does THIS element, on its own, carry content" check.
+  // Mirrors only the direct-content half of getContentNameInfo on purpose,
   // not a full name-from-content recursion: the whole point is to keep
   // recursing through plain wrapper elements (a framework's root mount
   // <div> included) until reaching the actual content-bearing node, rather

package/src/checks/manual/scope-attr-valid-manual.js

@@ -6,7 +6,7 @@
  * @check scope-attr-valid
  * @atomic true
  * @summary The scope attribute must have a valid value
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with a non-empty scope attribute.
  * @expectation
@@ -15,7 +15,7 @@
  *   assistive technology, silently losing the row/column header
  *   association it was meant to declare.
  * @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.
  */

package/src/checks/manual/scrollable-region-focusable-manual.js

@@ -9,10 +9,10 @@
  * @standard WCAG 2.2
  * @sc 2.1.1, 2.1.3
  * @applicability
- *   Deliberately scoped to a fixed set of likely-to-scroll container tags
+ *   Scoped on purpose to a fixed set of likely-to-scroll container tags
  *   (div, section, article, aside, main, nav, pre, table, blockquote, ul,
  *   ol, textarea) with computed `overflow-x`/`overflow-y` of `auto` or
- *   `scroll` — not every element on the page, to keep this deterministic
+ *   `scroll`, not every element on the page, to keep this deterministic
  *   and performant (same style of scope-down as `region`).
  * @expectation
  *   A region whose CSS declares it may scroll (`auto`/`scroll`) should be
@@ -22,18 +22,18 @@
  *   scroll from), or the region itself carries a non-negative `tabindex`.
  * @implementation-notes
  * - jsdom does not perform layout, so `scrollHeight`/`clientHeight` are
- *   not available to confirm the region's content actually overflows —
+ *   not available to confirm the region's content actually overflows,
  *   only that the CSS declares it *may*. Many elements declare
  *   `overflow: auto` defensively without their content ever actually
  *   overflowing, which would be a false positive if treated as a hard
  *   `fail`. For that reason this is authored as `type: 'manual'`
- *   (cantTell-capped, never fail) rather than `automatic` — same class of
- *   layout-dependent gap as `iframe-focusable-content`'s
+ *   (cantTell-capped, never fail) rather than `automatic`, the same class
+ *   of layout-dependent gap as `iframe-focusable-content`'s
  *   `contentDocument` limitation.
  * - "Has a focusable descendant" is a presence check (link/button/form
  *   control/`[tabindex]`/`iframe`/`[contenteditable]`), not a full
- *   focusability computation (disabled state, visibility, etc.) — a
- *   deliberate simplification to keep this rule self-contained and fast.
+ *   focusability computation (disabled state, visibility, etc.). Kept
+ *   simple on purpose, to keep this rule self-contained and fast.
  */
 
 const id = 'scrollable-region-focusable';

package/src/checks/manual/skip-link-manual.js

@@ -6,17 +6,17 @@
  * @check skip-link
  * @atomic true
  * @summary A "skip" link must resolve to a real, usable target
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to <a href="#fragment"> elements whose accessible name
  *   matches a common "skip to ..." / "jump to ..." authoring convention
- *   (case-insensitive "skip" or "jump to" in the name) — the recognizable
+ *   (case-insensitive "skip" or "jump to" in the name), the recognizable
  *   pattern for a skip-navigation link, not every same-page anchor link
  *   on the page. "jump to" is included alongside "skip" since real skip
  *   links use both conventions (e.g. a "Jump to section" link, which a
  *   purely positional match would catch but a "skip"-only text pattern
- *   would miss). Text-pattern matching itself stays deliberate (see
- *   implementation-notes) — this only widens the known-convention list.
+ *   would miss). Text-pattern matching itself stays intentional (see
+ *   implementation-notes); this only widens the known-convention list.
  * @expectation
  *   The link's fragment resolves to a real element in the document
  *   (via a matching id, or a legacy <a name="...">), and that target is
@@ -25,7 +25,7 @@
  *   whose target is missing or effectively unusable does not provide a
  *   reliable bypass destination.
  * @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.
  * - Keyed on the "skip" text-pattern convention rather than positional

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

@@ -9,6 +9,15 @@
  * @standard WCAG 2.2
  * @sc 1.1.1
  * @type manual
+ * @applicability
+ *   Applies to inline <svg> elements that already carry a text alternative:
+ *   non-empty <title> or <desc> text, a non-empty aria-label, or an
+ *   aria-labelledby that resolves to non-empty text. <desc> counts here as
+ *   something to review even though it never contributes to the accessible
+ *   name: that distinction is svg-text-alternative-present's. 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/tabindex-manual.js

@@ -6,7 +6,7 @@
  * @check tabindex
  * @atomic true
  * @summary tabindex should not be greater than 0
- * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
  *   Applies to elements with a tabindex attribute whose value parses as
  *   a valid integer.
@@ -16,7 +16,7 @@
  *   page changes and usually indicates the natural DOM order should be
  *   fixed instead.
  * @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.
  */