@surea11y/core 1.2.0 → 1.4.0

package/src/core/dom-runner.js

@@ -1,671 +0,0 @@
-'use strict';
-
-/**
- * DOM runner implementation.
- *
- * IMPORTANT:
- * - This function is inlined into generated core.js (Node + in-page runner).
- * - It intentionally references shared runtime helpers that core.js defines:
- *   resolvePolicy, POLICY_CONTRACTS, resolveRuleDefI18n, ruleMatchesRunOnly,
- *   normalizeRuleResult, normalizeLocale, createDomHelpers, normalizeSelectorList,
- *   resolveContextRoots (src/core/dom-helpers.js -- also used by frame-scan.js),
- *   normalizeRuleMeta (src/core/rule-meta.js -- used for engineOptions.customRules).
- */
-
-function runCore(pageUrl, contextSelector, engineOptions, runOnly, CHECK_DEFS, RULE_IMPLS, ENGINE_TAG, SCHEMA_VERSION, COMPOSITE_RULES) {
-    // Normalize contrast options without mutating caller-provided engineOptions.
-    function __normalizeContrastOptions(engineOptions2) {
-        const eo = engineOptions2 && typeof engineOptions2 === 'object' ? engineOptions2 : {};
-        const c = (eo.contrast && typeof eo.contrast === 'object') ? eo.contrast : {};
-        const mode = (c.mode === 'auditorAssist') ? 'auditorAssist' : 'strictConformance';
-        const rootCanvasFallback =
-            (typeof c.rootCanvasFallback === 'string' && c.rootCanvasFallback.trim())
-                ? c.rootCanvasFallback.trim()
-                : '#ffffff';
-        return { mode, rootCanvasFallback };
-    }
-
-    const engineOptionsResolved =
-        (engineOptions && typeof engineOptions === 'object')
-            ? { ...engineOptions, contrast: __normalizeContrastOptions(engineOptions) }
-            : { contrast: __normalizeContrastOptions(null) };
-
-    const policy = resolvePolicy(POLICY_CONTRACTS, engineOptionsResolved);
-
-    // contextSelector accepts a single selector string (which may itself be a
-    // comma-separated selector list -- ordinary CSS union semantics) OR an
-    // array of selector strings for scanning multiple, possibly disjoint
-    // regions in one run (a widely-used reference engine's multi-.include()
-    // capability has no equivalent here otherwise). Both forms resolve via querySelectorAll,
-    // not querySelector -- previously a single string only ever scanned its
-    // FIRST match, silently ignoring the rest if it happened to match more
-    // than one element. That was a real gap, not a deliberate "one region
-    // only" design: switched to querySelectorAll for both forms so
-    // "matches this selector" actually means all matches, consistently.
-    // Shared with frame-scan.js (same resolution used to discover which
-    // child <iframe>/<frame> elements fall within the same scan scope).
-    const { ctxSelector, roots } = resolveContextRoots(document, contextSelector);
-
-    // Default on: opt OUT with `includeShadowDom: false`, not opt in.
-    const includeShadowDom = !(engineOptionsResolved && engineOptionsResolved.includeShadowDom === false);
-    // Default off: hidden/collapsed content is excluded from rule evaluation
-    // unless the caller explicitly opts in.
-    const includeHiddenElements = !!(engineOptionsResolved && engineOptionsResolved.includeHiddenElements === true);
-    const excludeSelectors = normalizeSelectorList(engineOptionsResolved && engineOptionsResolved.excludeSelectors);
-    // Default off: explicit opt-in for "this scan target was never meant to
-    // represent a real page" -- see helpers.isWholeDocumentScope().
-    const fragment = !!(engineOptionsResolved && engineOptionsResolved.fragment === true);
-
-    const url = pageUrl || (document.location && document.location.href) || null;
-    const title = document.title || null;
-    // Deterministic timestamp: only use host-provided value (no time-based logic).
-    const timestamp =
-        (engineOptionsResolved && typeof engineOptionsResolved.timestamp === 'string' && engineOptionsResolved.timestamp.trim())
-            ? engineOptionsResolved.timestamp.trim()
-            : null;
-
-    // createDomHelpers()/createContrastHelpers() persist their element-keyed
-    // caches (outerHtmlCache, selectorCache, etc.) on window.__a11ycoreSharedCache
-    // so multiple helper instances created *within this run* can share them
-    // deterministically. But a window/document is frequently reused across
-    // SEPARATE runs -- e.g. Jest's jsdom environment creates one window per
-    // test file, and mutating document.body between it() blocks is standard.
-    // Those caches are keyed by element reference, not content, so a run that
-    // reuses an already-cached element (document.body never changes identity)
-    // would otherwise read stale data cached by an earlier, unrelated run on
-    // the same window. Clearing at the start of every run keeps sharing scoped
-    // to "this run" as intended, without leaking across runs.
-    try {
-        if (window && window.__a11ycoreSharedCache) window.__a11ycoreSharedCache = {};
-    } catch {}
-
-    const sharedHelpers = createDomHelpers({
-        document,
-        window,
-        root: roots,
-        includeShadowDom,
-        includeHiddenElements,
-        excludeSelectors,
-        fragment,
-        // Optional perf counters (bench/debug only). Deterministic and per-run.
-        perfStats: !!(engineOptionsResolved && engineOptionsResolved.perfStats)
-    });
-
-    const profileRules = !!(engineOptionsResolved && engineOptionsResolved.profileRules);
-    const ruleTimings = profileRules ? Object.create(null) : null;
-
-    function nowMs() {
-        // performance.now() if available, else Date.now()
-        try {
-            if (typeof performance !== 'undefined' && performance && typeof performance.now === 'function') {
-                return performance.now();
-            }
-        } catch (e) {}
-        return Date.now();
-    }
-
-    // =========================
-    // Probes (optional evidence fed by the host app)
-    // Keep deterministic + serializable + no-throws.
-    // =========================
-    function sanitizeProbeValue(v, depth) {
-        // depth-bounded, JSON-safe sanitizer
-        if (depth <= 0) return null;
-        if (v == null) return null;
-
-        const t = typeof v;
-        if (t === 'string') return v.length > 2000 ? v.slice(0, 2000) : v;
-        if (t === 'number') return Number.isFinite(v) ? v : null;
-        if (t === 'boolean') return v;
-        if (t === 'function') return null;
-
-        if (Array.isArray(v)) {
-            // cap arrays to avoid huge payloads
-            const out = [];
-            const n = Math.min(v.length, 200);
-            for (let i = 0; i < n; i++) out.push(sanitizeProbeValue(v[i], depth - 1));
-            return out;
-        }
-
-        if (t === 'object') {
-            const out = {};
-            const keys = Object.keys(v).sort();
-            // cap object keys
-            const n = Math.min(keys.length, 50);
-            for (let i = 0; i < n; i++) {
-                const k = keys[i];
-                // only allow string keys
-                if (typeof k !== 'string') continue;
-                out[k] = sanitizeProbeValue(v[k], depth - 1);
-            }
-            return out;
-        }
-
-        return null;
-    }
-
-    let probes = null;
-    try {
-        const rawProbes = engineOptionsResolved && typeof engineOptionsResolved.probes === 'object' ? engineOptionsResolved.probes : null;
-        probes = rawProbes ? sanitizeProbeValue(rawProbes, 6) : null;
-        if (!probes || typeof probes !== 'object' || Array.isArray(probes)) probes = null;
-    } catch (e) {
-        probes = null;
-    }
-
-    // =========================
-    // Runtime custom rules (engineOptions.customRules)
-    // =========================
-    // Same module shape as an internal rule file: { id, meta, runInPage, applicability?, data? }.
-    // runInPage/applicability may be a real function (fine for same-realm/Node/jsdom callers)
-    // or a function-source string (required for cross-realm callers, e.g. a Playwright
-    // page.evaluate(runa11yCoreInPage, { engineOptions }) call -- engineOptions crosses a
-    // structured-clone/JSON boundary there, so a live Function reference can't survive it,
-    // but a string can). Reconstructed via `new Function`, matching exactly how build-core.js
-    // already embeds each built-in rule's own runInPage source into the in-page runner.
-    // Scan-scoped only (not added to the static CHECK_DEFS/getRulesCatalog() catalog) --
-    // matches surea11y's existing "fresh engineOptions per call, no mutable global config"
-    // design (see ROADMAP.md), rather than a widely-used reference engine's stateful global configure().
-    let effectiveCheckDefs = CHECK_DEFS;
-    let effectiveRuleImpls = RULE_IMPLS;
-    let overriddenBuiltinIds = [];
-    const rawCustomRules = Array.isArray(engineOptionsResolved.customRules) ? engineOptionsResolved.customRules : [];
-    if (rawCustomRules.length) {
-        function reviveRuleFn(value) {
-            if (typeof value === 'function') return value;
-            if (typeof value === 'string' && value.trim()) {
-                try {
-                    const fn = new Function('return (' + value + ')')();
-                    if (typeof fn === 'function') return fn;
-                } catch (e) {
-                    return null;
-                }
-            }
-            return null;
-        }
-
-        const extraDefsById = new Map();
-        const extraImpls = {};
-        for (const c of rawCustomRules) {
-            if (!c || typeof c !== 'object') continue;
-            const ruleId = typeof c.id === 'string' ? c.id.trim() : '';
-            if (!ruleId) continue;
-            const runFn = reviveRuleFn(c.runInPage);
-            if (typeof runFn !== 'function') continue; // invalid custom rule: skipped, not a crash
-
-            const applicabilityFn = reviveRuleFn(c.applicability);
-            const normalizedMeta = normalizeRuleMeta(ruleId, ruleId, c.meta, ENGINE_TAG);
-
-            // Overriding a built-in rule id is supported (see docs/ENGINE_OPTIONS.md),
-            // but a same-named custom rule is just as likely to be an accidental
-            // collision (a generic name like "region" or "tabindex" picked without
-            // realizing it's already a built-in id) as a deliberate override -- so
-            // surface it either way rather than silently swapping the rule out.
-            if (CHECK_DEFS.some((d) => d && d.ruleId === ruleId)) {
-                overriddenBuiltinIds.push(ruleId);
-            }
-
-            extraDefsById.set(ruleId, {
-                ruleId,
-                title: normalizedMeta.title,
-                description: normalizedMeta.description,
-                i18n: normalizedMeta.i18n,
-                helpUrl: normalizedMeta.helpUrl,
-                tags: normalizedMeta.tags,
-                wcagSc: normalizedMeta.wcagSc,
-                normativeMappings: normalizedMeta.normativeMappings,
-                defaultSeverity: normalizedMeta.defaultSeverity,
-                defaultConfidence: normalizedMeta.defaultConfidence,
-                type: normalizedMeta.type,
-                coverage: normalizedMeta.coverage,
-                data: (c.data === undefined ? null : c.data),
-                ruleInterfaceVersion: normalizedMeta.ruleInterfaceVersion,
-                ruleVersion: normalizedMeta.ruleVersion,
-                normative: normalizedMeta.normative,
-                atomic: normalizedMeta.atomic,
-                deprecated: normalizedMeta.deprecated,
-                deprecation: normalizedMeta.deprecation,
-                category: normalizedMeta.category,
-                standard: normalizedMeta.standard,
-                applicability: normalizedMeta.applicability,
-                expectation: normalizedMeta.expectation,
-                references: normalizedMeta.references,
-                requirements: normalizedMeta.requirements,
-                mappings: normalizedMeta.mappings
-            });
-            extraImpls[ruleId] = { run: runFn, applicability: applicabilityFn || null };
-        }
-
-        if (extraDefsById.size) {
-            effectiveCheckDefs = CHECK_DEFS
-                .filter((d) => !extraDefsById.has(d.ruleId))
-                .concat(Array.from(extraDefsById.values()));
-            effectiveRuleImpls = { ...RULE_IMPLS, ...extraImpls };
-        }
-
-        if (overriddenBuiltinIds.length) {
-            try {
-                console.warn('[surea11y] customRules overriding built-in rule id(s) for this scan: ' + overriddenBuiltinIds.join(', '));
-            } catch (e) {}
-        }
-    }
-
-    const checksResults = [];
-
-    for (const def of effectiveCheckDefs) {
-        const t0 = ruleTimings ? nowMs() : 0;
-        const defResolved = resolveRuleDefI18n(def, engineOptionsResolved);
-        if (!ruleMatchesRunOnly(defResolved, runOnly, ENGINE_TAG)) continue;
-
-        const implEntry = effectiveRuleImpls[defResolved.ruleId];
-        const impl = implEntry && typeof implEntry.run === 'function' ? implEntry.run : null;
-        const applicabilityFn = implEntry && typeof implEntry.applicability === 'function' ? implEntry.applicability : null;
-        if (typeof impl !== 'function') continue;
-
-        const ruleConfig =
-            engineOptionsResolved && engineOptionsResolved.rules && engineOptionsResolved.rules[defResolved.ruleId]
-                ? engineOptionsResolved.rules[defResolved.ruleId]
-                : null;
-
-        // Rule-scoped excludeSelectors (engineOptions.rules[ruleId].excludeSelectors)
-        // apply on top of the global excludeSelectors for exactly this rule's
-        // applicability check + run, then are cleared once this rule is done.
-        // Safe because rule execution below is synchronous and one rule at a
-        // time -- sharedHelpers is reused across all rules in this loop.
-        if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
-            sharedHelpers.__setActiveRuleExcludeSelectors(ruleConfig && ruleConfig.excludeSelectors);
-        }
-
-        const ctx = {
-            document,
-            window,
-            root: roots,
-            rule: defResolved,
-            config: ruleConfig,
-            helpers: sharedHelpers,
-            engineTag: ENGINE_TAG,
-            contextSelector: ctxSelector,
-            engineOptions: (engineOptionsResolved && typeof engineOptionsResolved === 'object') ? engineOptionsResolved : {},
-
-            // Optional evidence channel provided by host app
-            inputs: {
-                probes
-            }
-        };
-
-        if (typeof applicabilityFn === 'function') {
-            let applicable = true;
-            try {
-                const res = applicabilityFn(ctx);
-                if (typeof res === 'boolean') applicable = res;
-                else if (res && typeof res === 'object' && typeof res.applicable === 'boolean') applicable = res.applicable;
-            } catch (err) {
-                const raw = {
-                    outcome: 'cantTell',
-                    occurrences: [],
-                    error: String(err && err.message ? err.message : err),
-                    engineOptions: { ...(ctx.engineOptions || {}), locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale) }
-                };
-                checksResults.push(normalizeRuleResult(defResolved, raw, SCHEMA_VERSION, policy, sharedHelpers));
-                if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
-                continue;
-            }
-
-            if (!applicable) {
-                const raw = {
-                    outcome: 'notApplicable',
-                    occurrences: [],
-                    engineOptions: { ...(ctx.engineOptions || {}), locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale) }
-                };
-                checksResults.push(normalizeRuleResult(defResolved, raw, SCHEMA_VERSION, policy, sharedHelpers));
-                if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
-                continue;
-            }
-        }
-
-        let result;
-        try {
-            result = impl(ctx);
-        } catch (err) {
-            result = {
-                outcome: 'cantTell',
-                occurrences: [],
-                error: String(err && err.message ? err.message : err),
-                engineOptions: { ...(ctx.engineOptions || {}), locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale) }
-            };
-        }
-
-        if (!result || typeof result !== 'object') {
-            if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
-            continue;
-        }
-        if (!result.engineOptions) {
-            result.engineOptions = { ...(ctx.engineOptions || {}), locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale) };
-        }
-        checksResults.push(normalizeRuleResult(defResolved, result, SCHEMA_VERSION, policy, sharedHelpers));
-        if (ruleTimings) ruleTimings[defResolved.ruleId] = (ruleTimings[defResolved.ruleId] || 0) + (nowMs() - t0);
-    }
-
-    // Composite rollups below carry no occurrences/nodes of their own, so
-    // they never exercise rule-scoped excludes -- but clear the "active
-    // rule" state on sharedHelpers regardless, so nothing after this point
-    // (composite aggregation, perf stats) can observe a stale rule's excludes.
-    if (typeof sharedHelpers.__setActiveRuleExcludeSelectors === 'function') {
-        sharedHelpers.__setActiveRuleExcludeSelectors(null);
-    }
-
-    // =========================
-    // Composite rule aggregation (data-only rollups)
-    // =========================
-    const rulesResults = [];
-    try {
-        const composites = Array.isArray(COMPOSITE_RULES) ? COMPOSITE_RULES : [];
-
-        // Determine target conformance level from runOnly.tags (already normalized by caller)
-        const LEVEL_RANK = { A: 1, AA: 2, AAA: 3 };
-
-        function inferTargetLevelFromRunOnly(runOnly2) {
-            const tags = runOnly2 && Array.isArray(runOnly2.tags) ? runOnly2.tags : [];
-            // tags are already lowercase
-            if (tags.includes('wcag2aaa') || tags.includes('wcag22aaa') || tags.includes('wcag21aaa')) return 'AAA';
-            if (tags.includes('wcag2aa') || tags.includes('wcag22aa') || tags.includes('wcag21aa')) return 'AA';
-            if (tags.includes('wcag2a') || tags.includes('wcag22a') || tags.includes('wcag21a')) return 'A';
-            return null; // if not specified, don't filter composites (back-compat)
-        }
-
-        function normalizeLevel(s) {
-            const v = typeof s === 'string' ? s.trim().toUpperCase() : '';
-            return (v === 'A' || v === 'AA' || v === 'AAA') ? v : null;
-        }
-
-        function isAllowedByTargetLevel(compositeLevel, targetLevel) {
-            if (!targetLevel) return true;
-            const c = LEVEL_RANK[compositeLevel];
-            const t = LEVEL_RANK[targetLevel];
-            if (!c || !t) return false; // unknown level => safest: exclude
-            return c <= t;
-        }
-
-        const targetLevel = inferTargetLevelFromRunOnly(runOnly);
-
-        // Severity rollup (deterministic)
-        const SEVERITY_RANK = { minor: 1, moderate: 2, serious: 3, critical: 4 };
-
-        function normalizeSeverity(s) {
-            const v = typeof s === 'string' ? s.trim().toLowerCase() : '';
-            return SEVERITY_RANK[v] ? v : null;
-        }
-
-        function maxSeverity(a, b) {
-            if (!a) return b || null;
-            if (!b) return a || null;
-            return (SEVERITY_RANK[b] > SEVERITY_RANK[a]) ? b : a;
-        }
-
-        // Index atomic results by ruleId (deterministic)
-        const byRuleId = Object.create(null);
-        for (const rr of checksResults) {
-            if (rr && typeof rr === 'object' && typeof rr.ruleId === 'string' && rr.ruleId) {
-                byRuleId[rr.ruleId] = rr;
-            }
-        }
-
-        function isNonEmptyString(s) {
-            return typeof s === 'string' && !!s.trim();
-        }
-
-        function buildCompositeDef(entry) {
-            if (!entry || typeof entry !== 'object') return null;
-
-            const ruleId = isNonEmptyString(entry.id) ? entry.id.trim() : String(entry.id || '').trim();
-            if (!ruleId) return null;
-
-            const metaIn = (entry.meta && typeof entry.meta === 'object' && !Array.isArray(entry.meta)) ? entry.meta : {};
-
-            const titleKey = (typeof metaIn.titleKey === 'string' && metaIn.titleKey.trim()) ? metaIn.titleKey.trim() : '';
-            const descriptionKey = (typeof metaIn.descriptionKey === 'string' && metaIn.descriptionKey.trim()) ? metaIn.descriptionKey.trim() : '';
-
-            const wcagSc = Array.isArray(metaIn.wcagSc) ? metaIn.wcagSc.map(String).map(s => s.trim()).filter(Boolean) : [];
-
-            const tags = [];
-            tags.push(String(ENGINE_TAG || 'a11ycore').toLowerCase());
-            tags.push('composite');
-
-            // Fixed WCAG-version-introduction lists (2.1 and 2.2 additions only -- every other
-            // SC, including all pre-2.1 ones, is WCAG 2.0 baseline). Keep in sync with
-            // src/coverage/wcag-version-map.js (the canonical copy the rule-authoring
-            // consistency test checks against) -- this one has to stay a self-contained
-            // literal since runCore is inlined via .toString() with no module access at runtime.
-            const WCAG21_NEW_SCS = ['1.3.4', '1.3.5', '1.3.6', '1.4.10', '1.4.11', '1.4.12', '1.4.13', '2.1.4', '2.2.6', '2.3.3', '2.5.1', '2.5.2', '2.5.3', '2.5.4', '2.5.5', '2.5.6', '4.1.3'];
-            const WCAG22_NEW_SCS = ['2.4.11', '2.4.12', '2.4.13', '2.5.7', '2.5.8', '3.2.6', '3.3.7', '3.3.8', '3.3.9'];
-            const isWcag22Sc = wcagSc.some((sc) => WCAG22_NEW_SCS.includes(sc));
-            const isWcag21Sc = !isWcag22Sc && wcagSc.some((sc) => WCAG21_NEW_SCS.includes(sc));
-            const versionTagPrefix = isWcag22Sc ? 'wcag22' : (isWcag21Sc ? 'wcag21' : 'wcag2');
-
-            const lvl = (typeof metaIn.level === 'string' ? metaIn.level.trim().toUpperCase() : '');
-            if (lvl === 'A') {
-                tags.push(versionTagPrefix + 'a');
-            } else if (lvl === 'AA') {
-                tags.push(versionTagPrefix + 'a', versionTagPrefix + 'aa');
-            } else if (lvl === 'AAA') {
-                tags.push(versionTagPrefix + 'a', versionTagPrefix + 'aa', versionTagPrefix + 'aaa');
-            }
-
-            // Build normativeMappings so downstream consumers (like adapters) can derive WCAG SC/level
-            const normativeMappingsFromMeta = wcagSc.map((sc) => {
-                const m = { standard: 'WCAG', requirement: sc };
-                if (lvl === 'A' || lvl === 'AA' || lvl === 'AAA') m.level = lvl;
-                return m;
-            });
-
-            const checksIds =
-                Array.isArray(entry.checksIds)
-                    ? entry.checksIds.map(String).map(s => s.trim()).filter(Boolean)
-                    : [];
-
-            return {
-                ruleId,
-                title: metaIn.title || ruleId,
-                description: metaIn.description || '',
-
-                i18n: (titleKey || descriptionKey) ? { titleKey: titleKey || '', descriptionKey: descriptionKey || '' } : null,
-
-                helpUrl: '',
-                tags,
-
-                normativeMappings: normativeMappingsFromMeta,
-
-                defaultSeverity: 'serious',
-                defaultConfidence: 'medium',
-                type: 'automatic',
-                coverage: null,
-
-                ruleInterfaceVersion: '1.0.0',
-                ruleVersion: '0.0.0',
-                normative: true,
-                atomic: false,
-                deprecated: false,
-                deprecation: null,
-                category: null,
-                standard: null,
-                applicability: '',
-                expectation: '',
-                references: [],
-                requirements: null,
-                mappings: null,
-
-                // optional catalog meta passthrough
-                data: {
-                    details: {
-                        kind: 'compositeRule',
-                        wcagSc,
-                        level: (typeof metaIn.level === 'string' && metaIn.level.trim()) ? metaIn.level.trim() : null
-                    }
-                },
-
-                __checksIds: checksIds
-            };
-        }
-
-        for (let i = 0; i < composites.length; i++) {
-            const entry = composites[i];
-            const cDef0 = buildCompositeDef(entry);
-            if (!cDef0) continue;
-
-            // Conformance-level gate: if scan is AA, suppress AAA composites even if tags match
-            const compositeLevel =
-                cDef0 &&
-                cDef0.data &&
-                cDef0.data.details &&
-                normalizeLevel(cDef0.data.details.level);
-
-            if (!isAllowedByTargetLevel(compositeLevel, targetLevel)) continue;
-
-            // Localize title/description (uses def.i18n.* keys)
-            const cDefResolved = resolveRuleDefI18n(cDef0, engineOptionsResolved);
-
-            // Apply same selection logic to composites
-            if (!ruleMatchesRunOnly(cDefResolved, runOnly, ENGINE_TAG)) continue;
-
-            const checksIds = Array.isArray(cDef0.__checksIds) ? cDef0.__checksIds : [];
-
-            // rollup metrics (stable order)
-            let failCount = 0;
-            let cantTellCount = 0;
-            let notApplicableCount = 0;
-            let passCount = 0;
-            let missingCount = 0;
-
-            const contributors = [];
-
-            let rolledFailSeverity = null;     // max severity among FAIL contributors
-            let rolledCantTellSeverity = null; // max severity among CANTTELL contributors (optional)
-
-            for (let j = 0; j < checksIds.length; j++) {
-                const tid = checksIds[j];
-                const child = tid ? byRuleId[tid] : null;
-
-                if (!child) {
-                    missingCount += 1;
-                    contributors.push({ testId: tid, outcome: 'missing' });
-                    continue;
-                }
-
-                const out = child.outcome;
-                const childSev = normalizeSeverity(child && child.severity);
-
-                contributors.push({ testId: tid, outcome: out, severity: childSev || null });
-
-                if (out === 'fail' && childSev) {
-                    rolledFailSeverity = maxSeverity(rolledFailSeverity, childSev);
-                } else if (out === 'cantTell' && childSev) {
-                    rolledCantTellSeverity = maxSeverity(rolledCantTellSeverity, childSev);
-                }
-
-                if (out === 'fail') failCount += 1;
-                else if (out === 'cantTell') cantTellCount += 1;
-                else if (out === 'notApplicable') notApplicableCount += 1;
-                else if (out === 'pass') passCount += 1;
-            }
-
-            // outcome precedence:
-            // fail if any fail
-            // cantTell if any cantTell OR missing and none fail
-            // notApplicable if all notApplicable (and there is at least one test)
-            // pass otherwise
-            let outcome = 'pass';
-            let reasonCode = 'composite.rollup.pass.otherwise';
-
-            if (failCount > 0) {
-                outcome = 'fail';
-                reasonCode = 'composite.rollup.fail.anyFail';
-            } else if (cantTellCount > 0) {
-                outcome = 'cantTell';
-                reasonCode = 'composite.rollup.cantTell.anyCantTell';
-            } else if (missingCount > 0) {
-                outcome = 'cantTell';
-                reasonCode = 'composite.rollup.cantTell.missingChild';
-            } else if (checksIds.length > 0 && notApplicableCount === checksIds.length) {
-                outcome = 'notApplicable';
-                reasonCode = 'composite.rollup.notApplicable.allInapplicable';
-            } else if (checksIds.length === 0) {
-                outcome = 'cantTell';
-                reasonCode = 'composite.rollup.cantTell.emptyComposite';
-            }
-
-            const raw = {
-                outcome,
-                occurrences: [],
-
-                // REQUIRED by your reporting schema (top-level)
-                summaryKey: 'Composite rule rollup',
-                i18nKey: 'composite_rollup_summary',
-                i18nParams: { reasonCode, testCount: String(checksIds.length) },
-
-                // REQUIRED by your reporting schema (machine-readable payload)
-                data: {
-                    details: {
-                        reasonCode,
-                        checksIds: checksIds.slice(),
-                        contributors,
-                        metrics: {
-                            failCount,
-                            cantTellCount,
-                            notApplicableCount,
-                            passCount,
-                            missingCount
-                        }
-                    }
-                },
-
-                engineOptions: {
-                    ...(engineOptionsResolved || {}),
-                    locale: normalizeLocale(engineOptionsResolved && engineOptionsResolved.locale)
-                }
-            };
-
-            // Promote composite severity based on contributors (deterministic).
-            // - If composite fails: use max severity among failing children.
-            // - If composite cantTell: use max severity among cantTell children (fallback to failing if you prefer).
-            if (outcome === 'fail' && rolledFailSeverity) {
-                raw.severity = rolledFailSeverity;
-            } else if (outcome === 'cantTell' && rolledCantTellSeverity) {
-                raw.severity = rolledCantTellSeverity;
-            }
-
-            rulesResults.push(normalizeRuleResult(cDefResolved, raw, SCHEMA_VERSION, policy, sharedHelpers));
-        }
-    } catch (e) {
-        // no-throws: omit rulesResults if anything goes wrong
-    }
-
-    // Optional perf counters passthrough (only when enabled). Deterministic.
-    let perfStats = null;
-    try {
-        if (engineOptionsResolved && engineOptionsResolved.perfStats && sharedHelpers && typeof sharedHelpers.getPerfStats === 'function') {
-            perfStats = sharedHelpers.getPerfStats();
-        }
-    } catch (e) {
-        perfStats = null;
-    }
-
-    if (ruleTimings) {
-        if (perfStats && engineOptionsResolved && engineOptionsResolved.profileRules) {
-            perfStats.ruleTimings = ruleTimings; // (whatever your timing map is)
-        }
-    }
-
-    return {
-        engine: { tag: ENGINE_TAG, schemaVersion: SCHEMA_VERSION },
-        url,
-        title,
-        timestamp,
-        perfStats,
-        contextSelector: ctxSelector,
-        checksResults,
-        rulesResults,
-        overriddenBuiltinIds
-    };
-}
-
-module.exports = { runCore };