@surea11y/core 1.3.0 → 1.4.0

package/src/core/frame-messaging.js

@@ -1,261 +0,0 @@
-'use strict';
-
-/**
- * postMessage-based RPC used to reach into cooperating child frames (same-
- * or cross-origin -- treated identically, exactly like a widely-used
- * reference engine's own runPartial/finishRun/frameMessenger protocol,
- * confirmed by reading that engine's _sendCommandToFrame/_collectResultsFromFrames
- * source directly rather than assuming). Used by frame-scan.js.
- *
- * Only matters for the "plain script injection" consumption mode (surea11y
- * loaded directly into a page with no automation driver -- see
- * docs/INTEGRATION.md's "Browser extension context" section). A Playwright-
- * driven scan doesn't need any of this: Playwright reaches cross-origin
- * frames unconditionally via CDP (see @surea11y/playwright's ROADMAP.md gap
- * #1), which is strictly better than what a cooperative postMessage protocol
- * can achieve. This exists for when there IS no automation driver.
- *
- * Zero free vars in each exported piece -- inlined into generated core.js
- * via inlineConstFunction (scripts/build-core.js), same as dom-helpers.js/
- * dom-runner.js/rule-meta.js. All functions here become sibling `const`
- * declarations in the same generated scope, so they may freely reference
- * each other (matching how resolveEffectiveRunOnly/ruleMatchesRunOnly/etc.
- * already do) -- but each is independently a zero-free-var function with
- * respect to anything OUTSIDE that shared generated scope.
- */
-
-const FRAME_RPC_CHANNEL = '__frame_rpc_v1__';
-
-function getFrameRpcRegistry(win) {
-  if (!win.__a11yCoreFrameRpc__) {
-    win.__a11yCoreFrameRpc__ = {
-      pending: new Map(),
-      seq: 0,
-      responder: null,
-      listening: false
-    };
-  }
-  return win.__a11yCoreFrameRpc__;
-}
-
-function installFrameRpcListener(win, channel) {
-  const registry = getFrameRpcRegistry(win);
-  if (registry.listening) return registry;
-
-  win.addEventListener('message', function a11yCoreFrameRpcListener(event) {
-    const data = event && event.data;
-    if (!data || data.__a11ycore !== true || data.channel !== channel) return;
-
-    if (data.type === 'ping') {
-      try {
-        event.source &&
-          event.source.postMessage(
-            { __a11ycore: true, channel: channel, requestId: data.requestId, type: 'pong' },
-            '*'
-          );
-      } catch (e) {
-        /* target gone/closed -- nothing to do */
-      }
-      return;
-    }
-
-    if (data.type === 'run') {
-      const responder = registry.responder;
-      if (typeof responder !== 'function') return; // no responder enabled here: unreachable, same as a widely-used reference engine's own limitation
-      Promise.resolve()
-        .then(function () {
-          return responder(data.payload);
-        })
-        .then(function (result) {
-          try {
-            event.source &&
-              event.source.postMessage(
-                {
-                  __a11ycore: true,
-                  channel: channel,
-                  requestId: data.requestId,
-                  type: 'result',
-                  payload: result
-                },
-                '*'
-              );
-          } catch (e) {
-            /* target gone/closed */
-          }
-        })
-        .catch(function (err) {
-          try {
-            event.source &&
-              event.source.postMessage(
-                {
-                  __a11ycore: true,
-                  channel: channel,
-                  requestId: data.requestId,
-                  type: 'error',
-                  payload: String(err && err.message ? err.message : err)
-                },
-                '*'
-              );
-          } catch (e) {
-            /* target gone/closed */
-          }
-        });
-      return;
-    }
-
-    // 'pong' | 'result' | 'error' -- resolve whichever pending request this replies to.
-    const pending = registry.pending.get(data.requestId);
-    if (!pending) return;
-    if (data.type === 'pong') {
-      pending.onPong();
-      return;
-    }
-    registry.pending.delete(data.requestId);
-    if (data.type === 'result') pending.resolve(data.payload);
-    else
-      pending.reject(
-        new Error(typeof data.payload === 'string' ? data.payload : 'surea11y frame RPC error')
-      );
-  });
-
-  registry.listening = true;
-  return registry;
-}
-
-function nextFrameRpcRequestId(win) {
-  const registry = getFrameRpcRegistry(win);
-  registry.seq += 1;
-  return (
-    'req_' +
-    Date.now().toString(36) +
-    '_' +
-    registry.seq +
-    '_' +
-    Math.random().toString(36).slice(2, 8)
-  );
-}
-
-/**
- * Pings a target frame's window; resolves true if a cooperating surea11y
- * responder answers within pingWaitTime (default 500ms, matching a widely-used
- * reference engine's own default), false otherwise. Never rejects -- "not reachable" is a normal,
- * expected outcome (most iframes on the web have no surea11y loaded at
- * all), not an error.
- */
-function pingFrame(win, targetWindow, pingWaitTime) {
-  installFrameRpcListener(win, FRAME_RPC_CHANNEL);
-  const registry = getFrameRpcRegistry(win);
-  const requestId = nextFrameRpcRequestId(win);
-  const waitMs = typeof pingWaitTime === 'number' ? pingWaitTime : 500;
-
-  return new Promise(function (resolve) {
-    let settled = false;
-    const timeout = setTimeout(function () {
-      if (settled) return;
-      settled = true;
-      registry.pending.delete(requestId);
-      resolve(false);
-    }, waitMs);
-
-    registry.pending.set(requestId, {
-      onPong: function () {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timeout);
-        registry.pending.delete(requestId);
-        resolve(true);
-      },
-      resolve: function () {},
-      reject: function () {}
-    });
-
-    try {
-      targetWindow.postMessage(
-        { __a11ycore: true, channel: FRAME_RPC_CHANNEL, requestId: requestId, type: 'ping' },
-        '*'
-      );
-    } catch (e) {
-      if (!settled) {
-        settled = true;
-        clearTimeout(timeout);
-        registry.pending.delete(requestId);
-        resolve(false);
-      }
-    }
-  });
-}
-
-/**
- * Sends a 'run' command to a target frame's window (already confirmed
- * reachable via pingFrame) and resolves with its reply payload, or rejects
- * on timeout (default 60s, matching a widely-used reference engine's own frameWaitTime default) or an
- * explicit error reply.
- */
-function sendFrameRunCommand(win, targetWindow, payload, frameWaitTime) {
-  installFrameRpcListener(win, FRAME_RPC_CHANNEL);
-  const registry = getFrameRpcRegistry(win);
-  const requestId = nextFrameRpcRequestId(win);
-  const waitMs = typeof frameWaitTime === 'number' ? frameWaitTime : 60000;
-
-  return new Promise(function (resolve, reject) {
-    const timeout = setTimeout(function () {
-      registry.pending.delete(requestId);
-      reject(new Error('surea11y frame RPC timed out waiting for a run result'));
-    }, waitMs);
-
-    registry.pending.set(requestId, {
-      onPong: function () {},
-      resolve: function (result) {
-        clearTimeout(timeout);
-        resolve(result);
-      },
-      reject: function (err) {
-        clearTimeout(timeout);
-        reject(err);
-      }
-    });
-
-    try {
-      targetWindow.postMessage(
-        {
-          __a11ycore: true,
-          channel: FRAME_RPC_CHANNEL,
-          requestId: requestId,
-          type: 'run',
-          payload: payload
-        },
-        '*'
-      );
-    } catch (e) {
-      clearTimeout(timeout);
-      registry.pending.delete(requestId);
-      reject(e);
-    }
-  });
-}
-
-/**
- * Registers this window as reachable by a parent frame's scan: `handler`
- * receives the run command's payload and must return a result (or a
- * Promise of one). Returns a disable() function that removes the responder
- * (the message listener itself stays installed -- harmless/idle -- so a
- * later re-enable doesn't need to re-attach it).
- */
-function enableFrameRpcResponder(win, handler) {
-  installFrameRpcListener(win, FRAME_RPC_CHANNEL);
-  const registry = getFrameRpcRegistry(win);
-  registry.responder = handler;
-  return function disable() {
-    if (registry.responder === handler) registry.responder = null;
-  };
-}
-
-module.exports = {
-  FRAME_RPC_CHANNEL,
-  getFrameRpcRegistry,
-  installFrameRpcListener,
-  nextFrameRpcRequestId,
-  pingFrame,
-  sendFrameRunCommand,
-  enableFrameRpcResponder
-};

package/src/core/frame-scan.js

@@ -1,190 +0,0 @@
-'use strict';
-
-/**
- * Cross-frame orchestration for the "plain script injection" consumption
- * mode (surea11y loaded directly into a page with no automation driver --
- * see docs/INTEGRATION.md's "Browser extension context" section). A
- * Playwright-driven scan doesn't need any of this (see
- * @surea11y/playwright's ROADMAP.md gap #1 -- CDP-level frame access is
- * unconditional, strictly better than what a cooperative protocol like this
- * one can achieve). This exists for when there is no automation driver, the
- * same situation a widely-used reference engine itself is built around.
- *
- * Inlined into generated core.js (via scripts/build-core.js), wrapped in its
- * OWN private IIFE together with its own local copies of CHECK_DEFS/
- * RULE_IMPLS/ENGINE_TAG/SCHEMA_VERSION/COMPOSITE_RULES and the shared
- * runnersSharedSource block (runCore, resolveEffectiveRunOnly,
- * resolveContextRoots, pingFrame, sendFrameRunCommand,
- * enableFrameRpcResponder, etc.) -- mirroring exactly how runa11yCoreInPage
- * itself achieves self-containment, and deliberately calling runCore(...)
- * directly here (not the sibling runa11yCoreInPage) so this stays
- * independent of the outer, Node-require-based RULE_IMPLS section. That
- * independence matters concretely: it's what lets these two functions be
- * used the exact same bundler-free way runa11yCoreInPage already is (raw
- * source injected into a page, e.g. a bookmarklet or a content script with
- * no build step) rather than requiring a real bundler to resolve `require()`
- * calls first. References runCore/resolveContextRoots/resolveEffectiveRunOnly/
- * pingFrame/sendFrameRunCommand/enableFrameRpcResponder/CHECK_DEFS/
- * RULE_IMPLS/ENGINE_TAG/SCHEMA_VERSION/COMPOSITE_RULES as free vars,
- * satisfied by that wrapping. Not requireable/testable in isolation for
- * that reason (same as dom-runner.js) -- test via the generated core.js
- * bundle instead.
- */
-
-/* global runCore, resolveContextRoots, resolveEffectiveRunOnly, pingFrame,
-   sendFrameRunCommand, enableFrameRpcResponder, CHECK_DEFS, RULE_IMPLS,
-   ENGINE_TAG, SCHEMA_VERSION, COMPOSITE_RULES */
-
-function findChildFrameElements(roots) {
-  const seen = new Set();
-  const out = [];
-  for (const root of roots) {
-    if (!root || typeof root.querySelectorAll !== 'function') continue;
-    let matches;
-    try {
-      matches = root.querySelectorAll('iframe, frame');
-    } catch (e) {
-      matches = [];
-    }
-    for (const el of matches) {
-      if (el && !seen.has(el)) {
-        seen.add(el);
-        out.push(el);
-      }
-    }
-  }
-  return out;
-}
-
-function getFrameElementUrl(el) {
-  try {
-    if (el.contentWindow && el.contentWindow.location && el.contentWindow.location.href) {
-      return el.contentWindow.location.href;
-    }
-  } catch (e) {
-    // Cross-origin: reading contentWindow.location.href itself throws. Fall
-    // back to the authored src attribute (always readable, any origin).
-  }
-  return el.getAttribute ? el.getAttribute('src') || null : null;
-}
-
-/**
- * Scans the current frame, then attempts to reach every direct child
- * <iframe>/<frame> within the same scan scope via the frame RPC protocol
- * (src/core/frame-messaging.js). A child that doesn't respond (no
- * cooperating surea11y loaded and enabled there via
- * a11yCoreEnableFrameResponder() -- the common case for most third-party
- * embeds, and the same real limitation a widely-used reference engine itself has for
- * non-cooperating frames) is reported as { url, error } rather than
- * aborting the scan, matching the non-fatal-per-frame philosophy already
- * established for the Playwright binding's .frames(true). A child that
- * does respond replies with its OWN complete { topFrame, frames } result,
- * recursively including ITS OWN nested frames -- a tree, not a flat list
- * (unlike the Playwright binding: that binding can flatten because
- * Playwright's page.frames() already gives a flat list regardless of
- * nesting depth; a postMessage relay can't know about a grandchild without
- * asking through the child first).
- *
- * @returns {Promise<{ topFrame: object, frames: Array<{url:string|null, topFrame?:object, frames?:Array, error?:string}> }>}
- */
-function runa11yCoreAcrossFrames(pageUrl, contextSelector, engineOptions, runOnly) {
-  const topFrame = runCore(
-    pageUrl,
-    contextSelector,
-    engineOptions,
-    resolveEffectiveRunOnly(engineOptions, runOnly),
-    CHECK_DEFS,
-    RULE_IMPLS,
-    ENGINE_TAG,
-    SCHEMA_VERSION,
-    COMPOSITE_RULES
-  );
-
-  const eo = engineOptions && typeof engineOptions === 'object' ? engineOptions : {};
-  const pingWaitTime = typeof eo.pingWaitTime === 'number' ? eo.pingWaitTime : undefined;
-  const frameWaitTime = typeof eo.frameWaitTime === 'number' ? eo.frameWaitTime : undefined;
-
-  const { roots } = resolveContextRoots(document, contextSelector);
-  const frameElements = findChildFrameElements(roots);
-
-  const framePromises = frameElements.map(function (el) {
-    const url = getFrameElementUrl(el);
-    let targetWindow = null;
-    try {
-      targetWindow = el.contentWindow || null;
-    } catch (e) {
-      targetWindow = null;
-    }
-    if (!targetWindow) {
-      return Promise.resolve({ url: url, error: 'frame has no accessible contentWindow' });
-    }
-
-    return pingFrame(window, targetWindow, pingWaitTime).then(function (reachable) {
-      if (!reachable) {
-        return {
-          url: url,
-          error:
-            'no surea11y frame responder detected (that frame never called a11yCoreEnableFrameResponder(), or has not finished loading yet)'
-        };
-      }
-      return sendFrameRunCommand(
-        window,
-        targetWindow,
-        { pageUrl: url, contextSelector: null, engineOptions: eo, runOnly: runOnly },
-        frameWaitTime
-      )
-        .then(function (result) {
-          return { url: url, topFrame: result.topFrame, frames: result.frames };
-        })
-        .catch(function (err) {
-          return { url: url, error: String(err && err.message ? err.message : err) };
-        });
-    });
-  });
-
-  return Promise.all(framePromises).then(function (frames) {
-    return { topFrame: topFrame, frames: frames };
-  });
-}
-
-/**
- * Opt-in: makes the CURRENT window reachable by a parent frame's
- * runa11yCoreAcrossFrames() call. A page calls this once (e.g. right after
- * loading surea11y) to become scannable from above. Deliberately a
- * separate, explicit call rather than an automatic side effect of loading
- * surea11y's code -- unlike a widely-used reference engine, whose mere
- * presence as a loaded <script> makes it listen automatically. surea11y's distribution model
- * (a function you call, not a script tag with load-time side effects)
- * doesn't have an equivalent "just including it" moment, and an explicit
- * opt-in is a clearer consent point besides -- it means every Node/jsdom
- * consumer that merely requires the module never gets a phantom
- * `window.addEventListener` they didn't ask for.
- *
- * The incoming run command's own engineOptions/runOnly are always used
- * as-is (matching a widely-used reference engine's own behavior: the parent's
- * request carries the options, the child just executes with them, no local
- * override) -- there's no origin/identity check on the sender beyond the
- * namespaced message envelope itself, matching that reference engine's own permissiveness here
- * (running a read-only scan and replying with DOM-derived results isn't a
- * privileged operation; the DOM content involved is no more sensitive than
- * what's already rendered on the page).
- *
- * @returns {function(): void} disable() -- stops responding to future scans
- */
-function a11yCoreEnableFrameResponder() {
-  return enableFrameRpcResponder(window, function (payload) {
-    return runa11yCoreAcrossFrames(
-      payload ? payload.pageUrl : null,
-      payload ? payload.contextSelector : null,
-      payload ? payload.engineOptions : {},
-      payload ? payload.runOnly : null
-    );
-  });
-}
-
-module.exports = {
-  findChildFrameElements,
-  getFrameElementUrl,
-  runa11yCoreAcrossFrames,
-  a11yCoreEnableFrameResponder
-};

package/src/core/rollup-composites.js

@@ -1,127 +0,0 @@
-'use strict';
-
-const LEVEL_RANK = Object.freeze({ A: 1, AA: 2, AAA: 3 });
-
-function normalizeScanLevel(scanLevel) {
-  if (scanLevel === 'A' || scanLevel === 'AA' || scanLevel === 'AAA') return scanLevel;
-  return null;
-}
-
-/**
- * Try to infer scan level deterministically from runOnly.tags if provided by the caller.
- * (If you already pass scanLevel explicitly, you can ignore this.)
- */
-function inferScanLevelFromRunOnly(runOnly) {
-  const tags = runOnly && Array.isArray(runOnly.tags) ? runOnly.tags : null;
-  if (!tags || tags.length === 0) return null;
-
-  // Common reference-engine-style tags; adjust if your app uses different ones.
-  if (tags.includes('wcag2aaa') || tags.includes('wcag22aaa')) return 'AAA';
-  if (tags.includes('wcag2aa') || tags.includes('wcag22aa')) return 'AA';
-  if (tags.includes('wcag2a') || tags.includes('wcag22a')) return 'A';
-
-  return null;
-}
-
-function isWithinTargetLevel(compositeLevel, scanLevel) {
-  const c = LEVEL_RANK[compositeLevel];
-  const s = LEVEL_RANK[scanLevel];
-  if (!c || !s) return false;
-  return c <= s;
-}
-
-function aggregateOutcome(childOutcomes) {
-  // Deterministic priority: fail > cantTell > pass > notApplicable
-  let hasPass = false;
-  let hasCantTell = false;
-
-  for (const o of childOutcomes) {
-    if (o === 'fail') return 'fail';
-    if (o === 'cantTell') hasCantTell = true;
-    else if (o === 'pass') hasPass = true;
-  }
-
-  if (hasCantTell) return 'cantTell';
-  if (hasPass) return 'pass';
-  return 'notApplicable';
-}
-
-/**
- * Roll up atomic rule results into composite (SC) results, filtered by target level.
- *
- * Inputs are plain JS objects/arrays; function never throws and is deterministic.
- */
-function rollupComposites({ atomicResults, composites, scanLevel, runOnly }) {
-  try {
-    const target = normalizeScanLevel(scanLevel) || inferScanLevelFromRunOnly(runOnly) || 'AAA'; // safest default: if unspecified, do not hide anything
-
-    const atomicByRuleId = Object.create(null);
-    if (Array.isArray(atomicResults)) {
-      for (const r of atomicResults) {
-        if (!r || typeof r.ruleId !== 'string') continue;
-        atomicByRuleId[r.ruleId] = r;
-      }
-    }
-
-    const out = [];
-    const list = Array.isArray(composites) ? composites : [];
-    for (const c of list) {
-      const level = c && c.meta && c.meta.level;
-      if (!isWithinTargetLevel(level, target)) continue;
-
-      const checksIds = Array.isArray(c.checksIds) ? c.checksIds : [];
-      const childOutcomes = checksIds.map((id) => {
-        const rr = atomicByRuleId[id];
-        return rr && typeof rr.outcome === 'string' ? rr.outcome : 'notApplicable';
-      });
-
-      const outcome = aggregateOutcome(childOutcomes);
-
-      // Deterministic i18n keys + structured details (matches your reporting schema expectations)
-      const i18nKey =
-        outcome === 'fail'
-          ? 'composite.outcome.fail'
-          : outcome === 'cantTell'
-            ? 'composite.outcome.cantTell'
-            : outcome === 'pass'
-              ? 'composite.outcome.pass'
-              : 'composite.outcome.notApplicable';
-
-      out.push({
-        ruleId: c.id,
-        outcome,
-        confidence: outcome === 'cantTell' ? 'low' : 'high',
-        summaryKey: i18nKey, // resolved at build-time by your i18n layer
-        i18nKey,
-        i18nParams: {
-          wcagSc: (c.meta && c.meta.wcagSc && c.meta.wcagSc[0]) || null,
-          level: level || null,
-          scanLevel: target
-        },
-        data: {
-          details: {
-            reasonCode:
-              outcome === 'cantTell'
-                ? 'oneOrMoreChecksCantTell'
-                : outcome === 'fail'
-                  ? 'oneOrMoreChecksFailed'
-                  : outcome === 'pass'
-                    ? 'allApplicableChecksPassed'
-                    : 'allChecksNotApplicable',
-            scanLevel: target,
-            compositeLevel: level || null,
-            checksIds,
-            childOutcomes
-          }
-        }
-      });
-    }
-
-    return out;
-  } catch (e) {
-    // no-throws guarantee
-    return [];
-  }
-}
-
-module.exports = { rollupComposites };