pour-engine 1.40.0 → 1.42.0

package/engine/rules/wcag/2.4.12-focus-not-obscured-enhanced.js

@@ -0,0 +1,17 @@
+// WCAG SC 2.4.12 Focus Not Obscured (Enhanced) (Level AAA)
+// 2.4.11's geometry with the containment requirement relaxed to any
+// overlap: the enhanced criterion allows NO part of a focused component to
+// be hidden by author-created content, and its Understanding names the
+// sticky footer that clips the bottom of a focused link as the failure.
+// Same review-not-fail discipline as the minimum rule: the snapshot proves
+// where an element sits now, not where focus will find it.
+import { createFocusObscuredRule } from './2.4.11-focus-not-obscured.js';
+
+export default createFocusObscuredRule({
+  id: 'focus-not-obscured-enhanced',
+  name: 'Fully unobscured focus',
+  tags: ['wcag22aaa', 'wcag2412'],
+  help: 'No part of a focused element may be hidden behind overlays (AAA)',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-enhanced.html',
+  partial: true,
+});

package/engine/rules/wcag/2.4.2-document-title.js

@@ -3,18 +3,17 @@
 // merely PRESENT satisfies the markup, not the criterion, so the two
 // well-known undescriptive shapes are checked as well.
 //
-// Tier one, failed: strings that are a stand-in under every reading.
-// "Untitled Document" is what an editor writes when the author wrote
-// nothing, and no page is ever about that.
+// Familiar template strings are review candidates, not proof of a missing
+// topic: a document can genuinely describe the HTML document title or an
+// artwork named Untitled 1.
 // Tier two, sent to a human: single generic words and framework scaffold
 // defaults. Almost always a leftover, but a gallery page really can be about
 // an artwork called "Untitled", and "Example Domain" really is the subject
 // of example.com. Those are somebody's call to make, not the engine's.
 // "New document", "New page" and "New tab" sit in tier two as well: a
 // document editor's creation screen, a wiki's new-page form or a
-// browser-style app's new-tab page is about exactly that, so only the
-// numbered editor default ("New Page 1", F25's example) is a certain
-// placeholder (2026-08-25 overnight audit).
+// browser-style app's new-tab page is about exactly that. Even numbered
+// editor-style titles remain a question about the actual subject.
 //
 // Deliberately NOT judged: whether a real-looking title matches the page it
 // sits on. That needs someone who can read the page, and guessing at it
@@ -63,8 +62,8 @@ export default {
     const normalized = title.replace(/\s+/g, ' ').toLowerCase();
     if (PLACEHOLDER.has(normalized) || /^(?:untitled|new (?:document|page|tab))[\s-]*\d+$/.test(normalized)) {
       return {
-        status: 'fail',
-        message: `“${title}” is a placeholder left by an editor or template. It gives no topic and no purpose, so a screen reader announces nothing useful when the page loads, and a row of open tabs, bookmarks or history entries becomes impossible to tell apart.`,
+        status: 'incomplete',
+        message: `“${title}” resembles a template title. Check whether it describes this page's actual topic or purpose; the same words can also be a legitimate subject or name.`,
         fix: 'Put this page\'s own subject in the title first, then the site name.',
       };
     }

package/engine/rules/wcag/2.4.4-link-text-generic.js

@@ -13,11 +13,9 @@
 //               it sits in. A "Read more" under a headline naming the
 //               article is a judgment call about whether that context really
 //               reaches the user, so this REVIEWS. It never asserts.
-//   2.4.9 (AAA) purpose must come from the link text ALONE, with the only
-//               exception being links whose purpose "would be ambiguous to
-//               users in general". A link named nothing but "Read more" is
-//               ambiguous to everyone, which is the exception failing to
-//               apply rather than saving it, so this FAILS.
+//   2.4.9 (AAA) requires a mechanism for purpose to be available from link
+//               text alone. A page may let users expand its link names,
+//               so a generic name in this snapshot still needs review.
 //
 // Judged on the ACCESSIBLE NAME, not the text content: a link written as
 // <a href="…" aria-label="Read more about the budget">Read more</a> is
@@ -31,6 +29,8 @@
 // normalizeName below): apostrophes become spaces, so "plus d informations"
 // is how "plus d'informations" — straight or typographic — must be listed.
 
+import { effectiveRole, implicitRole } from '../../lib/roles.js';
+
 const GENERIC = new Set([
   // English
   'read more', 'read more about this', 'more', 'much more', 'learn more',
@@ -83,6 +83,7 @@ export function createLinkPurposeRule({ id, impact, tags, help, helpUrl, verdict
     // link-name's finding, not this one.
     selector: 'a[href], [role="link"]',
     evaluate(element, { accessibleName }) {
+      if ((effectiveRole(element) ?? implicitRole(element)) !== 'link') return { status: 'pass' };
       const name = accessibleName(element);
       if (!name) return { status: 'pass' }; // nameless: link-name reports it
       const normalized = normalizeName(name);

package/engine/rules/wcag/2.4.6-heading-label-placeholder.js

@@ -0,0 +1,69 @@
+// WCAG SC 2.4.6 Headings and Labels (Level AA)
+// "Headings and labels describe topic or purpose." The criterion does not
+// require a heading or label to exist; it requires that one that IS there
+// says what its section or field is about. Whether real words do that
+// needs a reader. What the DOM can show is the opposite case: a heading or
+// label whose text is a page builder's scaffold string ("Add Your Heading
+// Text Here", "Lorem ipsum", "Heading 1") left in place, which describes
+// nothing by construction. Same two tiers as the page-title rule:
+//   - scaffold strings and lorem ipsum FAIL: no page is about them;
+//   - a single generic word ("Heading", "Title", "Label") is REVIEWED: an
+//     article can genuinely be titled "Untitled" and a design-system page
+//     can be about headings.
+// Empty headings belong to the best-practice empty-heading rule; missing
+// labels belong to 3.3.2 and 4.1.2. This rule reads visible text only and
+// never judges the meaning of ordinary words.
+const SCAFFOLD = new Set([
+  'add your heading text here', 'add a heading', 'add heading', 'your heading here', 'heading here',
+  'your title goes here', 'your title here', 'title goes here', 'title here', 'insert title here',
+  'insert heading here', 'heading text', 'heading goes here', 'section title here',
+  'placeholder', 'placeholder text', 'placeholder heading', 'label text', 'your label here',
+  'text here', 'enter text here', 'your text here', 'type here', 'sample heading', 'sample text',
+  'dummy text', 'dummy heading', 'todo', 'tbd', 'xxx', 'xxxx', 'asdf',
+  'this is a heading', 'this is a title', 'this is the heading', 'this is a label',
+  'new heading', 'new label', 'new section',
+]);
+const GENERIC = new Set([
+  'heading', 'title', 'subtitle', 'headline', 'label', 'untitled', 'header', 'text', 'default',
+  'section', 'section title', 'section heading', 'page title', 'field', 'input',
+]);
+// "Heading 1" … "Heading 6", "h1" … "h6", "Title 2": the numbered defaults
+// editors and builders insert.
+const NUMBERED = /^(?:heading|title|label|h)\s*[1-6]$/;
+
+export default {
+  id: 'heading-label-placeholder',
+  name: 'Placeholder headings and labels',
+  impact: 'moderate',
+  tags: ['wcag2aa', 'wcag246'],
+  help: 'Headings and labels must describe their topic or purpose, not be template text',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/headings-and-labels.html',
+  selector: 'h1, h2, h3, h4, h5, h6, [role="heading"], label, legend',
+  evaluate(element) {
+    const role = element.getAttribute('role');
+    if (/^h[1-6]$/i.test(element.tagName) && role && role !== 'heading') return { status: 'pass' };
+    const text = (element.textContent ?? '').replace(/\s+/g, ' ').trim();
+    if (!text) return { status: 'pass' };
+    const normalized = text.toLowerCase().replace(/[\s.:!…-]+$/, '');
+    const kind = /^h[1-6]$/i.test(element.tagName) || role === 'heading' ? 'heading' : 'label';
+    if (SCAFFOLD.has(normalized) || normalized.startsWith('lorem ipsum') || NUMBERED.test(normalized)) {
+      return {
+        status: 'fail',
+        message: `“${text}” is template text left in a ${kind}. It describes nothing, so a screen-reader user scanning by ${kind}s, or anyone reading the form, learns nothing from it.`,
+        fix: kind === 'heading'
+          ? 'Replace it with words that name what the section is about.'
+          : 'Replace it with words that name what the field asks for.',
+      };
+    }
+    if (GENERIC.has(normalized)) {
+      return {
+        status: 'incomplete',
+        message: `“${text}” is a generic ${kind}. Check whether it describes the topic of its section or the purpose of its field; the same word can also be a real subject or name.`,
+        fix: kind === 'heading'
+          ? 'Name the section\'s actual topic in the heading.'
+          : 'Name what the field asks for in the label.',
+      };
+    }
+    return { status: 'pass' };
+  },
+};

package/engine/rules/wcag/2.4.9-link-text-generic-only.js

@@ -4,28 +4,13 @@
 // threshold: the link text ALONE has to identify the purpose, and context
 // is not allowed to make up the difference.
 //
-// This one asserts where the AA rule reviews. The criterion's only escape is
-// links "where the purpose of the link would be ambiguous to users in
-// general", and a link named nothing but "Read more" is ambiguous to
-// everyone — which is the exception failing to apply rather than rescuing
-// it. Nothing about the surrounding page can change that reading, so there
-// is nothing here for a human to settle.
+// The criterion allows a mechanism that expands link names. F84 requires
+// checking that no such mechanism exists, which a name-only snapshot cannot
+// prove. Semantic ambiguity and alternative presentation remain review.
 //
-// Two matches stay in the review lane because the failure is not provable
-// (2026-08-25 corpus adjudication):
-//   · a name wrapped in a paired bracket or quote — "<details>" is a code
-//     term that names its destination exactly (one-sided decoration like
-//     python.org's CSS-generated ">>>More" prompt still asserts);
-//   · a name that is exactly "go" — every corpus hit was a brand logo
-//     ("Go" is the language's name), and a brand name identifies the link.
-//
-// A third, beside "go" (2026-08-25 overnight audit): the French entries
-// "plus" and "suite" are ordinary English words and, more to the point,
-// common English plan and product names (a "Plus" tier, a "Suite"). A
-// pricing link named "Plus" identifies its destination the way the Go logo
-// does, so outside a page declared French they review rather than assert.
-// On a link whose closest lang is French the generic reading ("more",
-// "continued") is the only one and the assertion stands.
+// The review wording distinguishes recognizable proper-name ambiguities
+// (Go, Plus, Suite and quoted code terms) from ordinary generic phrases.
+// Neither branch treats a phrase-list match as semantic proof.
 import { createLinkPurposeRule } from './2.4.4-link-text-generic.js';
 
 const FRENCH_ONLY_ENGLISH_NAMES = new Set(['plus', 'suite']);
@@ -50,8 +35,8 @@ export default createLinkPurposeRule({
       fix: 'If the name really is generic here, put the destination in the link text, e.g. "Read more about the 2026 budget".',
     };
     return {
-      status: 'fail',
-      message: `“${name}” gives no purpose on its own. 2.4.9 asks that the link text alone identify where a link goes, without relying on the sentence or heading around it, so anyone reading the page's links as a list can tell them apart.`,
+      status: 'incomplete',
+      message: `“${name}” appears generic when read alone. Check whether it identifies the destination in this context or whether a mechanism makes the link text descriptive. 2.4.9 permits such a mechanism; the initial link name alone cannot establish a failure.`,
       fix: 'Name the destination in the link text, e.g. "Read more about the 2026 budget".',
     };
   },

package/engine/rules/wcag/2.5.1-pointer-gesture-alternative.js

@@ -0,0 +1,98 @@
+// WCAG SC 2.5.1 Pointer Gestures (Level A)
+// Functionality operated by a path-based gesture (a swipe, a drag along a
+// track, a drawn shape) or a multipoint gesture (a pinch) must also work
+// with a single pointer and no path, unless the gesture is essential. The
+// gesture logic itself lives in script, which a scan cannot read. But a
+// page that implements its own swipe, pan or pinch has to tell the
+// browser to stand aside first, and it does that in one visible place: the
+// CSS touch-action property. `touch-action: none` hands every touch to
+// the script; `pan-y` keeps vertical scrolling native and hands horizontal
+// swipes (the carousel) to the script; `pan-x` the reverse; a value
+// without `pinch-zoom` hands the pinch (the map) to the script. Those
+// elements are the honest candidates. Whether the swipe or pinch has a
+// single-pointer twin (next and previous buttons, zoom buttons) is not
+// decidable from markup, so this asks and never asserts.
+//
+// Kept out, and why:
+//   - `auto` and `manipulation`: nothing is handed to script beyond the
+//     double-tap zoom delay.
+//   - `pan-x pan-y` (both axes native, only the pinch withheld): measured
+//     on the corpus as a scroll-snap carousel and "no pinch zoom" wrappers,
+//     never a pinch handler; the browser still does all the panning.
+//   - range inputs and role="slider": the Understanding says a slider that
+//     drifts off its track is not path-based, and G216 covers it.
+//   - draggable="true" elements: 2.5.7's question (drag-alternative).
+//   - elements under 100 by 60 px: a gesture surface that small is not one.
+// Only the outermost candidate in a subtree is reported, once; descendants
+// that inherit or repeat the declaration ride with it. Stylesheets a
+// cross-origin policy hides are not a problem here: the computed value on
+// the element is read, whatever sheet set it.
+const HANDLED = new Set(['auto', 'manipulation']);
+
+function handsGestureToScript(value) {
+  if (!value || HANDLED.has(value)) return false;
+  const tokens = value.split(/\s+/);
+  if (tokens.includes('none')) return true;
+  const panX = tokens.some((t) => /^pan-(x|left|right)$/.test(t));
+  const panY = tokens.some((t) => /^pan-(y|up|down)$/.test(t));
+  // One axis withheld is a swipe handler (pan-y is the carousel; pan-x the
+  // vertical one); both axes native is the browser scrolling as usual.
+  return !panX || !panY;
+}
+
+export default {
+  id: 'pointer-gesture-alternative',
+  name: 'Pointer gesture alternative',
+  impact: 'serious',
+  tags: ['wcag21a', 'wcag251'],
+  help: 'Swipe, pan and pinch gestures need a single-pointer alternative',
+  helpUrl: 'https://www.w3.org/WAI/WCAG22/Understanding/pointer-gestures.html',
+  selector: '*',
+  visibleOnly: false,
+  evaluateAll(elements, { isRendered }) {
+    const candidates = new Set();
+    for (const element of elements) {
+      const tag = element.tagName;
+      if (tag === 'HTML' || tag === 'BODY' || tag === 'SCRIPT' || tag === 'STYLE' || tag === 'LINK' || tag === 'META' || tag === 'TEMPLATE') continue;
+      // Cheap gates first: the style read is paid only by rendered boxes
+      // that could be a gesture surface at all.
+      if (element.getAttribute('draggable') === 'true' || element.getAttribute('role') === 'slider' || (tag === 'INPUT' && element.type === 'range')) continue;
+      const rect = element.getBoundingClientRect();
+      if (rect.width < 100 || rect.height < 60) continue;
+      if (!isRendered(element)) continue;
+      const value = getComputedStyle(element).touchAction;
+      if (!handsGestureToScript(value)) continue;
+      candidates.add(element);
+    }
+    // Outermost only, and one per row of siblings: a carousel's track,
+    // slides and images all inherit the same declaration (and a cloned
+    // slide strip repeats it eleven times, measured on a corpus home), and
+    // one question per gesture surface is enough.
+    const outermost = new Set();
+    const reportedParents = new Set();
+    for (const element of candidates) {
+      let nested = false;
+      for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+        if (candidates.has(parent)) { nested = true; break; }
+      }
+      if (nested || reportedParents.has(element.parentElement)) continue;
+      reportedParents.add(element.parentElement);
+      outermost.add(element);
+    }
+    return elements.map((element) => {
+      if (!outermost.has(element)) return { status: 'pass' };
+      const value = getComputedStyle(element).touchAction;
+      const tokens = value.split(/\s+/);
+      const handled = tokens.includes('none') ? 'every touch gesture'
+        : [
+          !tokens.some((t) => /^pan-(x|left|right)$/.test(t)) && 'horizontal swipes',
+          !tokens.some((t) => /^pan-(y|up|down)$/.test(t)) && 'vertical swipes',
+        ].filter(Boolean).join(' and ');
+      return {
+        status: 'incomplete',
+        message: `touch-action: ${value} tells the browser to hand ${handled} on this element to the page's own script, which is how custom swipe, pan and pinch interactions are built. 2.5.1 requires whatever those gestures do to also work with a single tap or click (previous and next buttons, zoom in and out, a choose-a-value control), unless the gesture is essential. Check a single-pointer way exists for everything the gesture does.`,
+        fix: 'Add plain buttons for the same actions (previous/next, zoom in/out), or make the element operable by simple clicks as well as gestures.',
+      };
+    });
+  },
+};