@surea11y/core 1.2.0 → 1.4.0

package/src/core/frame-messaging.js

@@ -1,210 +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,178 +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.
- */
-
-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,135 +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 };

package/src/core/rule-meta.js

@@ -1,159 +0,0 @@
-'use strict';
-
-/**
- * Normalizes a rule module's `meta` export into the stable shape CHECK_DEFS
- * entries use everywhere else (build-time rules and runtime-registered
- * custom rules alike).
- *
- * Zero free vars (besides its own params) -- this gets inlined into the
- * generated core.js runtime via inlineConstFunction, the same mechanism
- * dom-helpers.js/dom-runner.js use, so it must stay self-contained/embeddable
- * via .toString(). engineTag is a param (not a closed-over module constant)
- * for exactly that reason.
- */
-function normalizeRuleMeta(ruleId, id, meta, engineTag) {
-  function normalizeStringArray(value) {
-    if (!Array.isArray(value)) return [];
-    return value.map(String).map((s) => s.trim()).filter(Boolean);
-  }
-
-  function normalizeObjectArray(value) {
-    if (!Array.isArray(value)) return [];
-    return value
-        .filter((v) => v && typeof v === 'object' && !Array.isArray(v))
-        .map((v) => ({ ...v }));
-  }
-
-  function deriveWcagScFromNormativeMappings(normativeMappings) {
-    const nm = Array.isArray(normativeMappings) ? normativeMappings : [];
-    const out = new Set();
-    for (const m of nm) {
-      if (!m || typeof m !== 'object') continue;
-      if (String(m.standard || '').toUpperCase() !== 'WCAG') continue;
-      const req = String(m.requirement || '').trim();
-      if (req) out.add(req);
-    }
-    return Array.from(out).sort();
-  }
-
-  const m = (meta && typeof meta === 'object') ? meta : {};
-
-  const title = (typeof m.title === 'string' && m.title.trim()) ? m.title.trim() : id;
-  const description = (typeof m.description === 'string') ? m.description : '';
-  const helpUrl = (typeof m.helpUrl === 'string') ? m.helpUrl : '';
-
-  const i18n = (m.i18n && typeof m.i18n === 'object' && !Array.isArray(m.i18n))
-      ? { ...m.i18n }
-      : null;
-
-  const tags = normalizeStringArray(m.tags).map((t) => t.toLowerCase());
-  if (!tags.includes(engineTag)) tags.push(engineTag);
-
-  const normativeMappings = normalizeObjectArray(m.normativeMappings);
-  const wcagSc = deriveWcagScFromNormativeMappings(normativeMappings);
-  const informativeReferences = normalizeObjectArray(m.informativeReferences);
-
-  const defaultSeverity = (typeof m.defaultSeverity === 'string' && m.defaultSeverity.trim())
-      ? m.defaultSeverity.trim()
-      : 'moderate';
-
-  const defaultConfidence = (typeof m.defaultConfidence === 'string' && m.defaultConfidence.trim())
-      ? m.defaultConfidence.trim()
-      : 'medium';
-
-  const type = (m.type === 'manual' || m.type === 'automatic')
-      ? m.type
-      : 'automatic';
-
-  const coverage = (m.coverage === null || typeof m.coverage === 'string' || typeof m.coverage === 'object')
-      ? m.coverage
-      : null;
-
-  const ruleInterfaceVersion = (typeof m.ruleInterfaceVersion === 'string' && m.ruleInterfaceVersion.trim())
-      ? m.ruleInterfaceVersion.trim()
-      : '1.0.0';
-
-  const ruleVersion = (typeof m.ruleVersion === 'string' && m.ruleVersion.trim())
-      ? m.ruleVersion.trim()
-      : '0.0.0';
-
-  const normative = (typeof m.normative === 'boolean') ? m.normative : true;
-  const atomic = (typeof m.atomic === 'boolean') ? m.atomic : true;
-
-  // Deprecation signal for the rule catalog (see docs/API_STABILITY.md).
-  // Purely informational -- a deprecated rule still runs and produces
-  // results completely normally; this is a catalog-level migration signal
-  // for integrators, not an automatic exclusion.
-  const deprecated = (typeof m.deprecated === 'boolean') ? m.deprecated : false;
-  const deprecation = (deprecated && m.deprecation && typeof m.deprecation === 'object' && !Array.isArray(m.deprecation))
-      ? {
-          replacedBy: (typeof m.deprecation.replacedBy === 'string' && m.deprecation.replacedBy.trim()) ? m.deprecation.replacedBy.trim() : null,
-          reason: (typeof m.deprecation.reason === 'string') ? m.deprecation.reason.trim() : '',
-          sinceVersion: (typeof m.deprecation.sinceVersion === 'string') ? m.deprecation.sinceVersion.trim() : ''
-        }
-      : null;
-
-  if (deprecated && (!deprecation || !deprecation.reason || !deprecation.sinceVersion)) {
-    throw new Error(`Rule ${ruleId}: meta.deprecated:true requires meta.deprecation.reason and meta.deprecation.sinceVersion`);
-  }
-
-  const category = (typeof m.category === 'string' && m.category.trim()) ? m.category.trim() : null;
-  const standard = (typeof m.standard === 'string' && m.standard.trim()) ? m.standard.trim() : null;
-
-  const applicability = (typeof m.applicability === 'string') ? m.applicability : '';
-  const expectation = (typeof m.expectation === 'string') ? m.expectation : '';
-
-  const references = Array.isArray(m.references) ? m.references.slice() : [];
-  const requirements = (m.requirements === null || typeof m.requirements === 'string' || typeof m.requirements === 'object')
-      ? m.requirements
-      : null;
-
-  const mappings = (m.mappings === null || typeof m.mappings === 'string' || typeof m.mappings === 'object')
-      ? m.mappings
-      : null;
-
-  if (!Array.isArray(tags)) throw new Error(`Rule ${ruleId}: meta.tags must be an array`);
-  if (!Array.isArray(normativeMappings)) throw new Error(`Rule ${ruleId}: meta.normativeMappings must be an array`);
-  if (!Array.isArray(informativeReferences)) throw new Error(`Rule ${ruleId}: meta.informativeReferences must be an array`);
-  if (type !== 'automatic' && type !== 'manual') throw new Error(`Rule ${ruleId}: meta.type must be "automatic" or "manual"`);
-
-  if (i18n) {
-    if (typeof i18n.titleKey !== 'string' || !i18n.titleKey.trim()) {
-      throw new Error(`Rule ${ruleId}: meta.i18n.titleKey must be a non-empty string`);
-    }
-    if (i18n.descriptionKey != null && (typeof i18n.descriptionKey !== 'string' || !i18n.descriptionKey.trim())) {
-      throw new Error(`Rule ${ruleId}: meta.i18n.descriptionKey must be a non-empty string when provided`);
-    }
-  }
-
-  return {
-    title,
-    description,
-    i18n,
-    helpUrl,
-    tags,
-    wcagSc,
-    normativeMappings,
-    informativeReferences,
-    defaultSeverity,
-    defaultConfidence,
-    type,
-    coverage,
-
-    ruleInterfaceVersion,
-    ruleVersion,
-    normative,
-    atomic,
-    deprecated,
-    deprecation,
-    category,
-    standard,
-    applicability,
-    expectation,
-    references,
-    requirements,
-    mappings
-  };
-}
-
-module.exports = { normalizeRuleMeta };