@surea11y/core 1.1.2 → 1.3.0

package/src/core/rollup-composites.js

@@ -3,8 +3,8 @@
 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;
+  if (scanLevel === 'A' || scanLevel === 'AA' || scanLevel === 'AAA') return scanLevel;
+  return null;
 }
 
 /**
@@ -12,38 +12,38 @@ function normalizeScanLevel(scanLevel) {
  * (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;
+  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';
+  // 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;
+  return null;
 }
 
 function isWithinTargetLevel(compositeLevel, scanLevel) {
-    const c = LEVEL_RANK[compositeLevel];
-    const s = LEVEL_RANK[scanLevel];
-    if (!c || !s) return false;
-    return c <= s;
+  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';
+  // 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';
 }
 
 /**
@@ -51,85 +51,77 @@ function aggregateOutcome(childOutcomes) {
  *
  * 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;
-            }
-        }
+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
-                    }
-                }
-            });
+    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 [];
+      });
     }
+
+    return out;
+  } catch (e) {
+    // no-throws guarantee
+    return [];
+  }
 }
 
 module.exports = { rollupComposites };

package/src/core/rule-meta.js

@@ -14,14 +14,17 @@
 function normalizeRuleMeta(ruleId, id, meta, engineTag) {
   function normalizeStringArray(value) {
     if (!Array.isArray(value)) return [];
-    return value.map(String).map((s) => s.trim()).filter(Boolean);
+    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 }));
+      .filter((v) => v && typeof v === 'object' && !Array.isArray(v))
+      .map((v) => ({ ...v }));
   }
 
   function deriveWcagScFromNormativeMappings(normativeMappings) {
@@ -36,15 +39,14 @@ function normalizeRuleMeta(ruleId, id, meta, engineTag) {
     return Array.from(out).sort();
   }
 
-  const m = (meta && typeof meta === 'object') ? meta : {};
+  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 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 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);
@@ -53,59 +55,91 @@ function normalizeRuleMeta(ruleId, id, meta, engineTag) {
   const wcagSc = deriveWcagScFromNormativeMappings(normativeMappings);
   const informativeReferences = normalizeObjectArray(m.informativeReferences);
 
-  const defaultSeverity = (typeof m.defaultSeverity === 'string' && m.defaultSeverity.trim())
+  const defaultSeverity =
+    typeof m.defaultSeverity === 'string' && m.defaultSeverity.trim()
       ? m.defaultSeverity.trim()
       : 'moderate';
 
-  const defaultConfidence = (typeof m.defaultConfidence === 'string' && m.defaultConfidence.trim())
+  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 type = m.type === 'manual' || m.type === 'automatic' ? m.type : 'automatic';
 
-  const coverage = (m.coverage === null || typeof m.coverage === 'string' || typeof m.coverage === 'object')
+  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())
+  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 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;
 
-  const normative = (typeof m.normative === 'boolean') ? m.normative : true;
-  const atomic = (typeof m.atomic === 'boolean') ? m.atomic : true;
+  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 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 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')
+  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')
+  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`);
+    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`
+      );
     }
   }
 
@@ -127,6 +161,8 @@ function normalizeRuleMeta(ruleId, id, meta, engineTag) {
     ruleVersion,
     normative,
     atomic,
+    deprecated,
+    deprecation,
     category,
     standard,
     applicability,