@setsquare/review-sdk 0.0.1 → 0.1.0

package/dist/checks/rule-pack.js

@@ -25,7 +25,13 @@ import { LINK_PURPOSE_LINK_ONLY_HELP_URL, TARGET_SIZE_ENHANCED_HELP_URL, VISUAL_
  * boundary. Version every behavioural change via SETSQUARE_RULE_PACK_VERSION — it
  * feeds the ruleset digest.
  */
-export const SETSQUARE_RULE_PACK_VERSION = 'setsquare-rules@1';
+// @2 measures the character count with the real `ch` metric rather than a
+// half-em guess, scopes line spacing to paragraphs that have lines, and puts
+// the measurements in the message. @3 scopes the rule to blocks of text —
+// WCAG's own "more than one sentence" — and reports a VIOLATION rather than a
+// judgement, for consistency with how 2.1.2 already handles the same
+// mechanism clause.
+export const SETSQUARE_RULE_PACK_VERSION = 'setsquare-rules@6';
 export const SETSQUARE_RULE_IDS = [
     'setsquare-target-size-aaa',
     'setsquare-visual-presentation',
@@ -65,36 +71,131 @@ export function rulePackSource() {
           // because a rule author's care is not a boundary (D13).
           var href = (node.getAttribute('href') || '').split('#')[0].split('?')[0];
 
+          /*
+           * A DIGEST of the accessible name, never the name itself.
+           *
+           * The after() phase has to know whether two controls share a name,
+           * and for a while it read a data.name this check does not set — so
+           * the equivalent-by-name branch below could not fire at all, and
+           * every same-named small control was reported as a flat failure with
+           * the exception never considered. The fixture lane found it the day
+           * it first ran in a browser.
+           *
+           * The fix is not to start carrying the name: the rule above still
+           * holds, and this finding reads the same without the page's text. A
+           * 32-bit FNV-1a of the normalised name answers "same or not" without
+           * the value being recoverable from it, which is the only question
+           * after() asks.
+           */
+          var label = (node.getAttribute('aria-label') || node.textContent || '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .toLowerCase();
+          var nameKey = '';
+          if (label) {
+            var hash = 2166136261;
+            for (var c = 0; c < label.length; c += 1) {
+              hash ^= label.charCodeAt(c);
+              hash = (hash * 16777619) >>> 0;
+            }
+            nameKey = hash.toString(16);
+          }
+
           this.data({
             width: width,
             height: height,
             href: href,
+            nameKey: nameKey,
           });
 
           if (width >= 44 && height >= 44) return true;
 
-          // Inline exception: a target in a sentence or line of text is exempt.
+          /*
+           * INLINE EXCEPTION: the target is in a sentence or block of text.
+           *
+           * This PASSES rather than asking a person, and the difference is the
+           * whole point of the exception. An inline element with a text
+           * sibling in its parent IS in a sentence — that is what the phrase
+           * describes, and the DOM says so plainly. The check used to detect
+           * exactly this condition and then return needs-review with the
+           * comment "a person decides", which sent every reference link in
+           * every paragraph of this repository's own site to a human with
+           * nothing to decide: the exception it had just matched exempts them.
+           */
           var display = window.getComputedStyle(node).display;
           if (display === 'inline' || display === 'inline-block') {
             var parent = node.parentElement;
             if (parent) {
               for (var i = 0; i < parent.childNodes.length; i += 1) {
                 var sibling = parent.childNodes[i];
-                if (sibling.nodeType === 3 && sibling.textContent && sibling.textContent.trim()) {
-                  // Sits amongst text: the inline exception may apply — a person decides.
-                  return undefined;
+                if (
+                  sibling !== node &&
+                  sibling.nodeType === 3 &&
+                  sibling.textContent &&
+                  sibling.textContent.trim()
+                ) {
+                  this.data({
+                    width: width,
+                    height: height,
+                    href: href,
+                    nameKey: nameKey,
+                    exception: 'inline',
+                  });
+                  return true;
                 }
               }
             }
           }
 
-          // User-agent exception: unstyled native checkboxes/radios are the
-          // browser's own size, which the SC exempts.
+          /*
+           * USER-AGENT EXCEPTION: the size is the browser's and the author has
+           * not modified it.
+           *
+           * Also decidable, by asking the browser. An unstyled control of the
+           * same kind is rendered once, measured, and removed; a control
+           * matching that size is the user agent's own and is exempt, and one
+           * that does not match has been resized by somebody and is not. The
+           * check used to return needs-review for every native checkbox and
+           * radio without looking, which exempts the author's 20px checkbox
+           * along with the browser's.
+           */
           if (
             node.tagName === 'INPUT' &&
             (node.type === 'checkbox' || node.type === 'radio')
           ) {
-            return undefined;
+            var cache = (window.__setsquareUaSize = window.__setsquareUaSize || {});
+            var reference = cache[node.type];
+            if (reference === undefined) {
+              reference = null;
+              try {
+                var probe = document.createElement('input');
+                probe.type = node.type;
+                probe.setAttribute('aria-hidden', 'true');
+                probe.style.position = 'absolute';
+                probe.style.left = '-9999px';
+                document.body.appendChild(probe);
+                var probeRect = probe.getBoundingClientRect();
+                reference = { w: Math.round(probeRect.width), h: Math.round(probeRect.height) };
+                probe.remove();
+              } catch (e) {
+                reference = null;
+              }
+              cache[node.type] = reference;
+            }
+
+            if (reference && width === reference.w && height === reference.h) {
+              this.data({
+                width: width,
+                height: height,
+                href: href,
+                nameKey: nameKey,
+                exception: 'user-agent',
+              });
+              return true;
+            }
+            // Resized by the author, so the exception does not apply and the
+            // measurement stands.
+            return false;
           }
 
           // Deterministically small; the Equivalent exception is ruled out (or
@@ -102,22 +203,52 @@ export function rulePackSource() {
           return false;
         },
         after: function (results) {
-          // Equivalent exception: another target with the same function
-          // (approximated by accessible name / destination) that IS large
-          // enough. Cannot be decided per-node, so it is decided here, and it
-          // downgrades a failure to needs-review rather than deleting it — the
-          // heuristic sees a name match, not a genuine functional equivalent.
-          var bigEnough = {};
+          /*
+           * EQUIVALENT EXCEPTION, split by how certain it is.
+           *
+           * The SC exempts a target reachable through an equivalent control on
+           * the same page that IS big enough. Two ways to match one, and they
+           * do not deserve the same answer:
+           *
+           *   same destination — the same normalised href, big enough
+           *     somewhere else on the page. Same href is the same link; that
+           *     is the exception, and it PASSES.
+           *
+           *   same name only — a control with the same accessible name and a
+           *     different destination. That may be a genuine equivalent and
+           *     may be a coincidence of wording, and nothing in the DOM says
+           *     which. Needs-review, which is what this exception is actually
+           *     uncertain about.
+           *
+           * Both used to collapse into needs-review. Only the second one is a
+           * judgement.
+           */
+          var bigByHref = {};
+          var bigByName = {};
           results.forEach(function (result) {
-            if (result.result === true && result.data) {
-              var key = result.data.href || result.data.name;
-              if (key) bigEnough[key] = true;
+            /*
+             * Passed ON SIZE, not passed for any reason. A row carrying an
+             * exception passed BECAUSE it is small and exempt — an inline link
+             * in a sentence, a 13px browser checkbox — and letting one of those
+             * stand as the "equivalent control that is big enough" would exempt
+             * every other small control sharing its name or destination on the
+             * strength of something smaller still.
+             */
+            if (result.result === true && result.data && !result.data.exception) {
+              if (result.data.href) bigByHref[result.data.href] = true;
+              if (result.data.nameKey) bigByName[result.data.nameKey] = true;
             }
           });
           results.forEach(function (result) {
-            if (result.result === false && result.data) {
-              var key = result.data.href || result.data.name;
-              if (key && bigEnough[key]) result.result = undefined;
+            if (result.result !== false || !result.data) return;
+            if (result.data.href && bigByHref[result.data.href]) {
+              result.data.exception = 'equivalent-href';
+              result.result = true;
+              return;
+            }
+            if (result.data.nameKey && bigByName[result.data.nameKey]) {
+              result.data.exception = 'equivalent-name';
+              result.result = undefined;
             }
           });
           return results;
@@ -125,10 +256,17 @@ export function rulePackSource() {
         metadata: {
           impact: 'moderate',
           messages: {
-            pass: 'Target is at least 44 by 44 CSS pixels',
-            fail: 'Target is smaller than 44 by 44 CSS pixels and no exception applies',
+            pass: 'Target is at least 44 by 44 CSS pixels, or an exception applies',
+            fail:
+              'Target measures \${data.width} by \${data.height} CSS pixels against the 44 by 44 ' +
+              'WCAG 2.5.5 asks for, and none of the SC exceptions applies: it is not in a ' +
+              'sentence, it is not a control the browser sized, and nothing else on the page ' +
+              'goes to the same place at a larger size.',
             incomplete:
-              'Target is smaller than 44 by 44 CSS pixels; an exception (inline, user-agent default, or an equivalent control) may apply — needs a person',
+              'Target measures \${data.width} by \${data.height} CSS pixels. Another control on ' +
+              'the page shares its name at a larger size, which MAY be the equivalent-control ' +
+              'exception — same wording is not the same function, and nothing in the markup ' +
+              'says which. A person decides that one.',
           },
         },
       },
@@ -136,51 +274,149 @@ export function rulePackSource() {
         // WCAG 1.4.8 Visual Presentation, AAA. Implemented from the W3C
         // Understanding document for 1.4.8 (linked as this rule's helpUrl).
         // Scoped to the prongs an author actively defeats: justified text,
-        // fixed line-height below 1.5, and measures past 80 characters
-        // (40 for CJK). Always needs-review — the SC requires a MECHANISM be
-        // available, so a conflicting default is a signal, never a verdict.
+        // fixed line spacing below 1.5, and measures past 80 characters
+        // (40 for CJK) — and only on a BLOCK of text, which WCAG defines as
+        // more than one sentence.
         id: 'setsquare-visual-presentation-defaults',
         evaluate: function (node) {
           var style = window.getComputedStyle(node);
           var problems = [];
 
-          if (style.textAlign === 'justify') problems.push('justified');
+          /*
+           * A BLOCK OF TEXT IS MORE THAN ONE SENTENCE. That is WCAG's own
+           * definition, and applying the SC without it is why this rule used
+           * to fire on card titles, standfirsts and one-line labels — a
+           * two-line heading styled as a paragraph has no leading to be
+           * insufficient and no measure to be too wide.
+           *
+           * Counted as sentence-ending punctuation followed by a space or the
+           * end of the text, which over-counts an abbreviation and under-counts
+           * a sentence ending in a bracket. Both errors are small and both
+           * point the same way — towards saying nothing.
+           *
+           * Note the DOUBLE backslash. This file is one long template literal,
+           * so a single one is eaten on the way out: the first version emitted
+           * a class followed by (s|$), which matches a full stop followed by a
+           * literal letter s, so nothing counted as a sentence and the whole
+           * rule silently passed everything on the site it was written for.
+           * Check the emitted source, not this one.
+           *
+           * And no backticks in this comment, for the reason the file header
+           * gives — one ends the string, and the parse error lands three
+           * checks away from the character that caused it. Which is how this
+           * note came to be rewritten.
+           */
+          var text = (node.textContent || '').trim();
+          var sentences = (text.match(/[.!?…](\\s|$)/g) || []).length;
+          if (sentences < 2) return true;
+
+          if (style.textAlign === 'justify') problems.push('justified text');
 
           var fontSize = parseFloat(style.fontSize);
           var lineHeight = parseFloat(style.lineHeight);
+          var rect = node.getBoundingClientRect();
+
+          // Line spacing is a property of a paragraph that HAS lines. A
+          // one-line paragraph — a standfirst, a label, a caption — has no
+          // leading to be insufficient, and flagging it reported a design
+          // decision as an accessibility signal.
+          var wraps =
+            isFinite(lineHeight) && lineHeight > 0 ? rect.height > lineHeight * 1.5 : false;
+
           if (
+            wraps &&
             style.lineHeight !== 'normal' &&
             isFinite(lineHeight) &&
             isFinite(fontSize) &&
             fontSize > 0 &&
             lineHeight / fontSize < 1.5
           ) {
-            problems.push('line-height ' + (Math.round((lineHeight / fontSize) * 100) / 100));
+            problems.push(
+              'line spacing ' +
+                (Math.round((lineHeight / fontSize) * 100) / 100) +
+                ' (needs 1.5)'
+            );
           }
 
           var lang = (node.closest('[lang]') || document.documentElement)
             .getAttribute('lang');
           var cjk = /^(ja|zh|ko)/i.test(lang || '');
-          var width = node.getBoundingClientRect().width;
-          // Approximate rendered measure: CJK glyphs are square (one em); Latin
-          // averages about half an em.
-          var chars = cjk ? width / fontSize : width / (fontSize * 0.5);
+
+          /*
+           * ONE CHARACTER IS THE WIDTH OF "0" IN THIS ELEMENT'S OWN FONT.
+           *
+           * That is what the CSS \`ch\` unit means and it is the conventional
+           * proxy for a character. The first version assumed half an em, which
+           * is wrong for every real typeface and wrong in the direction that
+           * manufactures findings: a measure set to 68ch by hand reported as
+           * ~90 characters and was flagged on every prose block of this
+           * repository's own site. The probe is memoised on the font string,
+           * because a page asks about the same three fonts a hundred times.
+           */
+          var probes = (window.__setsquareChProbe = window.__setsquareChProbe || {});
+          var font =
+            style.fontStyle + ' ' + style.fontWeight + ' ' + style.fontSize + ' ' +
+            style.fontFamily;
+          var chWidth = probes[font];
+          if (chWidth === undefined) {
+            chWidth = 0;
+            try {
+              var probeCtx = (probes.__ctx =
+                probes.__ctx || document.createElement('canvas').getContext('2d'));
+              if (probeCtx) {
+                probeCtx.font = font;
+                chWidth = probeCtx.measureText('0').width;
+              }
+            } catch (e) {
+              chWidth = 0;
+            }
+            probes[font] = chWidth;
+          }
+
+          // CJK glyphs are square — one em each — so they need no probe.
+          var perChar = cjk ? fontSize : chWidth;
+          var chars = perChar > 0 ? rect.width / perChar : 0;
           var limit = cjk ? 40 : 80;
-          if (isFinite(chars) && chars > limit) {
-            problems.push('measure ~' + Math.round(chars) + ' chars (limit ' + limit + ')');
+          if (isFinite(chars) && chars > 0 && chars > limit) {
+            problems.push('measure ' + Math.round(chars) + ' characters (limit ' + limit + ')');
           }
 
           if (problems.length === 0) return true;
           this.data({ problems: problems.join('; ') });
-          return undefined;
+
+          /*
+           * A VIOLATION, not needs-review, and the change is about being
+           * consistent with our own precedent rather than about the SC moving.
+           *
+           * 1.4.8 asks that a MECHANISM be available to achieve these, and no
+           * check can see a mechanism — which is exactly the shape of 2.1.2,
+           * where the SC also accepts a mechanism the page documents in text
+           * and we report the trap as a violation while saying so. Reporting
+           * one as a failure and the other as a judgement was incoherent.
+           *
+           * The stronger reason: a needs-review row on every block of prose is
+           * a number nobody acts on, and the measurement here is not in doubt.
+           * The page's default presentation either meets the SC's numbers or
+           * it does not; whether something elsewhere lets a user override it
+           * is a question the finding raises rather than one it pretends to
+           * have answered.
+           */
+          return false;
         },
         metadata: {
           impact: 'minor',
           messages: {
-            pass: 'Text block defaults do not conflict with 1.4.8',
-            fail: 'Text block presentation fails 1.4.8',
-            incomplete:
-              'Defaults conflict with 1.4.8; a user mechanism may still satisfy it — needs a person',
+            pass: 'Text block presentation meets the 1.4.8 numbers',
+            fail:
+              'Measured \${data.problems}. WCAG 1.4.8 asks for text that is not justified, ' +
+              'line spacing of at least 1.5 within paragraphs, and a measure of no more than ' +
+              '80 characters. Line spacing INHERITS, so a run of these usually has one cause ' +
+              'in a type scale or a container rather than one per block — worth checking ' +
+              'before editing anything. The SC is also met by a mechanism the page offers to ' +
+              'change the presentation, which this check cannot see, so a reading-preferences ' +
+              'control would change the answer.',
+            // Kept for completeness; the check no longer returns undefined.
+            incomplete: 'Text block presentation against 1.4.8 could not be measured',
           },
         },
       },
@@ -207,17 +443,86 @@ export function rulePackSource() {
           ];
           var isVague = vague.indexOf(name) !== -1 || /^https?:\\/\\//.test(name);
 
-          if (!isVague) return true;
-          this.data({ name: name.slice(0, 80) });
-          return undefined;
+          /*
+           * A DIGEST of the destination, for the after() phase below. Never
+           * the href itself: this rule already carries the page's own link
+           * text, which D13 allowed because for 2.4.9 the name IS the finding,
+           * and that permission does not extend to a second page-derived
+           * value. The only question after() asks is "same destination or
+           * not", and a hash answers it.
+           */
+          var href = (node.getAttribute('href') || '').split('#')[0].split('?')[0];
+          var hash = 2166136261;
+          for (var c = 0; c < href.length; c += 1) {
+            hash ^= href.charCodeAt(c);
+            hash = (hash * 16777619) >>> 0;
+          }
+
+          this.data({ name: name.slice(0, 80), hrefKey: hash.toString(16) });
+
+          /*
+           * A FAILURE, not a question.
+           *
+           * 2.4.9 asks that the purpose be identifiable from the link text
+           * ALONE — that is the whole difference between it and 2.4.4, which
+           * is the AA criterion and does allow context. "Click here" does not
+           * identify a purpose in any context, and the SC's exception is for
+           * links whose purpose is ambiguous to users in general, which is
+           * about the destination being genuinely unknowable rather than
+           * permission for lazy text.
+           *
+           * Reported at minor impact because the vague list is ours: the SC
+           * names no phrases,
+           * so this is a closed set of English wordings standing in for "does
+           * not describe its purpose", and the name is in the message so an
+           * author can see what we matched.
+           */
+          return !isVague;
+        },
+        after: function (results) {
+          /*
+           * The other half of 2.4.9, which nothing here was doing: TWO links
+           * with the same text going to different places.
+           *
+           * The text cannot identify the purpose of either, because it is the
+           * same text for two purposes. axe's own identical-links-same-purpose
+           * finds this and reports incomplete — reasonably, since it is a
+           * generic rule — but the SC's requirement is readable: same name,
+           * different destination, so the name alone does not distinguish
+           * them.
+           *
+           * Same name AND same destination is not a finding at all. A
+           * "Documentation" link in a header and another in a footer are the
+           * same link twice, which is how sites are built.
+           */
+          var destinations = {};
+          results.forEach(function (result) {
+            if (!result.data || !result.data.name) return;
+            var seen = destinations[result.data.name];
+            if (!seen) destinations[result.data.name] = { key: result.data.hrefKey, many: false };
+            else if (seen.key !== result.data.hrefKey) seen.many = true;
+          });
+          results.forEach(function (result) {
+            if (result.result === false || !result.data || !result.data.name) return;
+            var seen = destinations[result.data.name];
+            if (seen && seen.many) {
+              result.data.ambiguous = true;
+              result.result = false;
+            }
+          });
+          return results;
         },
         metadata: {
           impact: 'minor',
           messages: {
             pass: 'Link text describes its purpose',
-            fail: 'Link text does not describe its purpose',
-            incomplete:
-              'Link text alone may not describe its purpose ("click here", "read more", a bare URL) — needs a person',
+            fail:
+              'Link text does not identify the purpose of the link on its own. 2.4.9 asks for ' +
+              'the purpose to be identifiable from the text ALONE — that is what separates it ' +
+              'from 2.4.4, which is the AA criterion and does allow surrounding context. ' +
+              'Resolve it by saying where the link goes: "Read the 2.4.9 criterion" rather ' +
+              'than "read more".',
+            incomplete: 'Link purpose could not be assessed',
           },
         },
       },

package/dist/checks/rule-pack.js.map

@@ -1 +1 @@
-{"version":3,"file":"rule-pack.js","sourceRoot":"","sources":["../../src/checks/rule-pack.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAE/D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,2BAA2B;IAC3B,+BAA+B;IAC/B,wBAAwB;CAChB,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAuMa,6BAA6B;;;;;;;;;;;;;sBAa7B,4BAA4B;;;;;;;;;;;;sBAY5B,+BAA+B;;;;;GAKlD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"rule-pack.js","sourceRoot":"","sources":["../../src/checks/rule-pack.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,+BAA+B,EAC/B,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,0EAA0E;AAC1E,6EAA6E;AAC7E,0EAA0E;AAC1E,8EAA8E;AAC9E,qEAAqE;AACrE,oBAAoB;AACpB,MAAM,CAAC,MAAM,2BAA2B,GAAG,mBAAmB,CAAC;AAE/D,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,2BAA2B;IAC3B,+BAA+B;IAC/B,wBAAwB;CAChB,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sBAkfa,6BAA6B;;;;;;;;;;;;;sBAa7B,4BAA4B;;;;;;;;;;;;sBAY5B,+BAA+B;;;;;GAKlD,CAAC;AACJ,CAAC"}

package/dist/checks/shortcuts.d.ts

@@ -0,0 +1,71 @@
+import type { Page } from '@playwright/test';
+import type { DynamicCheckEvidence } from './dynamic.js';
+/**
+ * WCAG 2.1.4 Character Key Shortcuts (A): a single-character shortcut with no
+ * way to turn it off or remap it makes a page unusable for anyone using speech
+ * input, because every dictated word is a volley of shortcuts.
+ *
+ * A small rule and a real failure — and the only one in this package that
+ * needs to run BEFORE the customer's own code. There is no way to enumerate a
+ * page's event listeners after the fact: `getEventListeners` is a DevTools
+ * API and does not exist in page script. So the only route is to wrap
+ * `addEventListener` at init time and watch what gets registered.
+ *
+ * ---------------------------------------------------------------------------
+ * **Opt-in, and off by default, because of the footprint.**
+ *
+ * Everything else this SDK does happens after a page has loaded and can be
+ * undone. This patches a DOM method before any of the customer's scripts run,
+ * for the whole life of the page. Even proven inert, that is a larger presence
+ * in someone's application than a scanner has any business having by default —
+ * and "it is only a pass-through" is exactly the reasoning that precedes a
+ * subtle break in someone else's product.
+ *
+ * So it is a choice, `keyShortcuts: true`, and while it is off the criterion
+ * reports as a check that exists and did not run here, which is what it is.
+ *
+ * **Inertness, concretely.** The wrapper records `(type, target)` and the key
+ * literals it can read out of the handler's own source, then delegates with
+ * the ORIGINAL arguments — never a wrapped listener. That last part is what
+ * keeps `removeEventListener` working: a wrapped listener is a different
+ * function object and would never match, so a page that adds and removes a
+ * handler would silently keep it forever. The fixture asserts exactly that.
+ * ---------------------------------------------------------------------------
+ */
+export declare const SETSQUARE_SHORTCUTS_CHECK_VERSION = "setsquare-shortcuts@1";
+export declare const KEY_SHORTCUTS_RULE_ID = "setsquare-key-shortcuts";
+/**
+ * Installed before any page script. See the class comment for why this is
+ * opt-in; see `fixture.ts` for where it is installed.
+ *
+ * A source string rather than a function, because `addInitScript` serialises
+ * it and a closure over anything in this module would not survive.
+ */
+export declare const KEY_LISTENER_SCRIPT = "\n(() => {\n  const found = [];\n  Object.defineProperty(window, '__setsquareKeyListeners', {\n    value: found,\n    // Non-enumerable so it does not appear in a customer's own iteration over\n    // window, and non-writable so page code cannot clobber it by accident.\n    enumerable: false,\n    writable: false,\n    configurable: true,\n  });\n\n  const KEY_EVENTS = new Set(['keydown', 'keypress', 'keyup']);\n  const MODIFIER = /\\b(ctrlKey|metaKey|altKey|shiftKey|getModifierState)\\b/;\n\n  /*\n   * Which keys a handler reacts to, read out of its own source.\n   *\n   * The instrumentation can see THAT a key listener exists and never which key\n   * it cares about \u2014 so without this the finding would be \"this page has a\n   * keydown handler\", which is true of most of the web and useful to nobody.\n   * Reading the source is a heuristic and is treated as one: everything this\n   * rule reports is needs-review.\n   *\n   * A handler that consults a modifier is not what 2.1.4 is about, so it is\n   * left alone. That is most of the false positives.\n   */\n  const keysIn = (source) => {\n    if (typeof source !== 'string' || source.length === 0) return [];\n    if (source.indexOf('[native code]') !== -1) return [];\n    if (MODIFIER.test(source)) return [];\n\n    const keys = new Set();\n    const literal = /(?:\\.key\\s*={2,3}\\s*|case\\s+)['\"]([^'\"\\\\]{1})['\"]/g;\n    let match;\n    while ((match = literal.exec(source)) !== null) {\n      const key = match[1];\n      // Printable, single character, not whitespace. Enter, Escape and Tab are\n      // multi-character names and fall out here, which is right: 2.1.4 is\n      // about character keys.\n      if (key.trim().length === 1) keys.add(key);\n    }\n\n    const code = /(?:keyCode|which)\\s*={2,3}\\s*(\\d{2,3})/g;\n    while ((match = code.exec(source)) !== null) {\n      const value = Number(match[1]);\n      // Letters and digits only. The named keys have codes too, and reporting\n      // Escape as a character shortcut would be wrong.\n      if (value >= 48 && value <= 57) keys.add(String(value - 48));\n      else if (value >= 65 && value <= 90) keys.add(String.fromCharCode(value).toLowerCase());\n    }\n\n    return [...keys];\n  };\n\n  const original = EventTarget.prototype.addEventListener;\n  EventTarget.prototype.addEventListener = function (type, listener, options) {\n    try {\n      if (KEY_EVENTS.has(type) && (this === document || this === window) && found.length < 40) {\n        let source = '';\n        try {\n          source = typeof listener === 'function' ? Function.prototype.toString.call(listener) : '';\n        } catch {}\n        const keys = keysIn(source);\n        if (keys.length > 0) {\n          found.push({ type, target: this === window ? 'window' : 'document', keys });\n        }\n      }\n    } catch {}\n\n    /*\n     * The original arguments, never a wrapper. A wrapped listener is a\n     * different function object, so removeEventListener would never match it\n     * and a page that adds and removes a handler would silently keep it for\n     * ever. That is the failure this line exists to prevent.\n     */\n    return original.call(this, type, listener, options);\n  };\n})();\n";
+export interface KeyShortcutRow {
+    /** `keydown`, `keypress` or `keyup`. */
+    type: string;
+    /** `document` or `window`. */
+    target: string;
+    /** The single characters the handler's own source compares against. */
+    keys: string[];
+}
+/**
+ * Read what the instrumentation saw. Returns nothing when it was never
+ * installed, which is the honest answer for an opt-in check that is off.
+ */
+export declare function runKeyShortcuts(page: Page): Promise<DynamicCheckEvidence>;
+/**
+ * The verdict, and it is always needs-review or inapplicable — never a
+ * violation, and the reason is worth stating rather than assuming.
+ *
+ * 2.1.4 is satisfied if the shortcut can be turned off, remapped, or is only
+ * active when a specific component has focus. All three are page-level
+ * affordances: the first two live in a settings screen we are not looking at,
+ * and the third is a property of the handler's own logic. We can see that a
+ * handler compares against `j`; we cannot see whether the user was ever
+ * offered a way to stop it. Reporting a violation from what we CAN see would
+ * be asserting the part we cannot.
+ */
+export declare function keyShortcutEvidence(rows: readonly KeyShortcutRow[]): DynamicCheckEvidence;
+//# sourceMappingURL=shortcuts.d.ts.map

package/dist/checks/shortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shortcuts.d.ts","sourceRoot":"","sources":["../../src/checks/shortcuts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAI7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,eAAO,MAAM,iCAAiC,0BAA0B,CAAC;AAEzE,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAK/D;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,2qGA+E/B,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAW/E;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,GAAG,oBAAoB,CA0CzF"}