@surea11y/core 1.2.0 → 1.3.0

package/src/policy/contracts.js

@@ -1,18 +1,18 @@
 'use strict';
 
 module.exports = {
-    POLICY_CONTRACTS: {
-        a11y: {
-            id: 'a11y',
-            allowedOutcomes: ['fail', 'pass', 'cantTell', 'notApplicable'],
-            allowedConfidence: ['high', 'medium', 'low'],
-            coerceManualFailToCantTell: true
-        },
-        generic: {
-            id: 'generic',
-            allowedOutcomes: ['fail', 'pass', 'cantTell', 'notApplicable'],
-            allowedConfidence: ['high', 'medium', 'low'],
-            coerceManualFailToCantTell: false
-        }
+  POLICY_CONTRACTS: {
+    a11y: {
+      id: 'a11y',
+      allowedOutcomes: ['fail', 'pass', 'cantTell', 'notApplicable'],
+      allowedConfidence: ['high', 'medium', 'low'],
+      coerceManualFailToCantTell: true
+    },
+    generic: {
+      id: 'generic',
+      allowedOutcomes: ['fail', 'pass', 'cantTell', 'notApplicable'],
+      allowedConfidence: ['high', 'medium', 'low'],
+      coerceManualFailToCantTell: false
     }
+  }
 };

package/src/policy/resolvePolicy.js

@@ -1,55 +1,59 @@
 'use strict';
 
 function resolvePolicy(POLICY_CONTRACTS, engineOptions) {
-    function normalizePolicyContract(POLICY_CONTRACTS, contract, fallbackId) {
-        const fallback = POLICY_CONTRACTS[fallbackId] || POLICY_CONTRACTS.a11y;
-        if (typeof contract === 'string') return POLICY_CONTRACTS[contract] || fallback;
-
-        if (contract && typeof contract === 'object') {
-            const allowedOutcomes = Array.isArray(contract.allowedOutcomes)
-                ? contract.allowedOutcomes.slice()
-                : fallback.allowedOutcomes.slice();
-
-            const allowedConfidence = Array.isArray(contract.allowedConfidence)
-                ? contract.allowedConfidence.slice()
-                : fallback.allowedConfidence.slice();
-
-            return {
-                id: (typeof contract.id === 'string' && contract.id.trim())
-                    ? contract.id.trim()
-                    : (fallback.id || fallbackId || 'custom'),
-                allowedOutcomes,
-                allowedConfidence,
-                coerceManualFailToCantTell:
-                    typeof contract.coerceManualFailToCantTell === 'boolean'
-                        ? contract.coerceManualFailToCantTell
-                        : !!fallback.coerceManualFailToCantTell
-            };
-        }
-
-        return fallback;
-    }
-
-    function normalizePolicyOverrides(policy) {
-        const p = (policy && typeof policy === 'object') ? policy : {};
-        return {
-            allowedOutcomes: Array.isArray(p.allowedOutcomes) ? p.allowedOutcomes.slice() : null,
-            allowedConfidence: Array.isArray(p.allowedConfidence) ? p.allowedConfidence.slice() : null,
-            coerceManualFailToCantTell: typeof p.coerceManualFailToCantTell === 'boolean' ? p.coerceManualFailToCantTell : null
-        };
+  function normalizePolicyContract(POLICY_CONTRACTS, contract, fallbackId) {
+    const fallback = POLICY_CONTRACTS[fallbackId] || POLICY_CONTRACTS.a11y;
+    if (typeof contract === 'string') return POLICY_CONTRACTS[contract] || fallback;
+
+    if (contract && typeof contract === 'object') {
+      const allowedOutcomes = Array.isArray(contract.allowedOutcomes)
+        ? contract.allowedOutcomes.slice()
+        : fallback.allowedOutcomes.slice();
+
+      const allowedConfidence = Array.isArray(contract.allowedConfidence)
+        ? contract.allowedConfidence.slice()
+        : fallback.allowedConfidence.slice();
+
+      return {
+        id:
+          typeof contract.id === 'string' && contract.id.trim()
+            ? contract.id.trim()
+            : fallback.id || fallbackId || 'custom',
+        allowedOutcomes,
+        allowedConfidence,
+        coerceManualFailToCantTell:
+          typeof contract.coerceManualFailToCantTell === 'boolean'
+            ? contract.coerceManualFailToCantTell
+            : !!fallback.coerceManualFailToCantTell
+      };
     }
 
-    const opts = (engineOptions && typeof engineOptions === 'object') ? engineOptions : {};
-    const contract = normalizePolicyContract(POLICY_CONTRACTS, opts.policyContract, 'a11y');
-    const ov = normalizePolicyOverrides(opts.policy);
+    return fallback;
+  }
 
+  function normalizePolicyOverrides(policy) {
+    const p = policy && typeof policy === 'object' ? policy : {};
     return {
-        contractId: contract.id,
-        allowedOutcomes: ov.allowedOutcomes || contract.allowedOutcomes.slice(),
-        allowedConfidence: ov.allowedConfidence || contract.allowedConfidence.slice(),
-        coerceManualFailToCantTell:
-            ov.coerceManualFailToCantTell !== null ? ov.coerceManualFailToCantTell : !!contract.coerceManualFailToCantTell
+      allowedOutcomes: Array.isArray(p.allowedOutcomes) ? p.allowedOutcomes.slice() : null,
+      allowedConfidence: Array.isArray(p.allowedConfidence) ? p.allowedConfidence.slice() : null,
+      coerceManualFailToCantTell:
+        typeof p.coerceManualFailToCantTell === 'boolean' ? p.coerceManualFailToCantTell : null
     };
+  }
+
+  const opts = engineOptions && typeof engineOptions === 'object' ? engineOptions : {};
+  const contract = normalizePolicyContract(POLICY_CONTRACTS, opts.policyContract, 'a11y');
+  const ov = normalizePolicyOverrides(opts.policy);
+
+  return {
+    contractId: contract.id,
+    allowedOutcomes: ov.allowedOutcomes || contract.allowedOutcomes.slice(),
+    allowedConfidence: ov.allowedConfidence || contract.allowedConfidence.slice(),
+    coerceManualFailToCantTell:
+      ov.coerceManualFailToCantTell !== null
+        ? ov.coerceManualFailToCantTell
+        : !!contract.coerceManualFailToCantTell
+  };
 }
 
 module.exports = { resolvePolicy };

package/src/report.js

@@ -4,20 +4,13 @@
  * Renders one scan result into a single, self-contained HTML report (no
  * external CSS/JS/fonts -- opens straight from disk, no server, no network).
  *
- * Structurally adapted from the sibling cross-engine-diff project's own HTML
- * report tool (~/dev/surea11y/comparisons/cross-engine/render-html-report.js)
- * -- that tool's shell (self-contained single file, hero bar + legend,
- * grouped "worth reviewing" cards with an overflow cap, collapsible
- * "full technical data" with a scorecard + searchable/filterable/paginated
- * table, dark-mode CSS) is generic and reusable; everything here is written
- * fresh for a single-engine scan result, not copied, since that tool's own
- * organizing principle (a 7-way "does surea11y vs axe-core agree" taxonomy)
- * has no single-engine analog.
+ * Self-contained single file: hero bar + legend, grouped "worth reviewing"
+ * cards with an overflow cap, collapsible "full technical data" with a
+ * scorecard + searchable/filterable/paginated table, dark-mode CSS.
  */
 
-// Same 4-status vocabulary/palette as the reference tool (the dataviz
-// skill's validated status palette) -- maps 1:1 onto this engine's own
-// 4 outcomes, so no new palette is needed.
+// Uses the dataviz skill's validated status palette, mapped 1:1 onto this
+// engine's own 4 outcomes.
 const STATUS = {
   good: { color: '#0ca30c', bg: '#e9f7e9', icon: '✓' },
   serious: { color: '#c1502e', bg: '#fdece5', icon: '⚠' },
@@ -26,8 +19,7 @@ const STATUS = {
 };
 
 // fail first: a QA tester scanning a report wants violations up front,
-// matching axe-html-reporter/accessibility-insights-report's own convention
-// of leading with violations, not passes.
+// not passes.
 const OUTCOME_ORDER = ['fail', 'cantTell', 'pass', 'notApplicable'];
 const OUTCOME_INFO = {
   fail: { label: 'Fail', status: 'serious', defaultOn: true },
@@ -40,7 +32,10 @@ for (const code of OUTCOME_ORDER) {
 }
 
 function esc(s) {
-  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+  return String(s == null ? '' : s).replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]
+  );
 }
 
 // Neutralizes '<' so embedded JSON can never break out of its <script> tag,
@@ -69,8 +64,7 @@ function renderHeroBar(byOutcome) {
   const total = OUTCOME_ORDER.reduce((sum, c) => sum + byOutcome[c], 0) || 1;
   const applicable = byOutcome.pass + byOutcome.fail + byOutcome.cantTell;
 
-  const segments = OUTCOME_ORDER
-    .filter((c) => byOutcome[c] > 0)
+  const segments = OUTCOME_ORDER.filter((c) => byOutcome[c] > 0)
     .map((c) => {
       const n = byOutcome[c];
       const pct = (n / total) * 100;
@@ -79,17 +73,15 @@ function renderHeroBar(byOutcome) {
     })
     .join('');
 
-  const legend = OUTCOME_ORDER
-    .map((c) => {
-      const n = byOutcome[c];
-      const info = OUTCOME_INFO[c];
-      return `<div class="hero-legend-item">
+  const legend = OUTCOME_ORDER.map((c) => {
+    const n = byOutcome[c];
+    const info = OUTCOME_INFO[c];
+    return `<div class="hero-legend-item">
         <span class="hero-legend-swatch" style="background:${info.color}">${info.icon}</span>
         <span class="hero-legend-label">${esc(info.label)}</span>
         <span class="hero-legend-count">${n.toLocaleString()} (${fmtPct(n, total)})</span>
       </div>`;
-    })
-    .join('\n');
+  }).join('\n');
 
   let headline;
   if (byOutcome.fail > 0) {
@@ -134,7 +126,8 @@ function renderWcagRollup(rulesResults) {
 
   const byLevel = { A: [], AA: [], AAA: [], other: [] };
   for (const r of rulesResults) {
-    const mapping = (r.meta && Array.isArray(r.meta.normativeMappings) && r.meta.normativeMappings[0]) || null;
+    const mapping =
+      (r.meta && Array.isArray(r.meta.normativeMappings) && r.meta.normativeMappings[0]) || null;
     const level = (mapping && mapping.level) || 'other';
     (byLevel[level] || byLevel.other).push({ rule: r, mapping });
   }
@@ -143,7 +136,13 @@ function renderWcagRollup(rulesResults) {
     .filter((level) => byLevel[level].length)
     .map((level) => {
       const rows = byLevel[level]
-        .sort((a, b) => (a.mapping ? a.mapping.requirement : '').localeCompare(b.mapping ? b.mapping.requirement : '', undefined, { numeric: true }))
+        .sort((a, b) =>
+          (a.mapping ? a.mapping.requirement : '').localeCompare(
+            b.mapping ? b.mapping.requirement : '',
+            undefined,
+            { numeric: true }
+          )
+        )
         .map(({ rule, mapping }) => {
           const info = OUTCOME_INFO[rule.outcome] || OUTCOME_INFO.notApplicable;
           const metrics = (rule.data && rule.data.details && rule.data.details.metrics) || {};
@@ -176,8 +175,12 @@ function renderWcagRollup(rulesResults) {
 // the findings table below shows the untruncated value.
 const CARD_SNIPPET_MAX = 220;
 function truncateForCard(s) {
-  const collapsed = String(s || '').replace(/\s+/g, ' ').trim();
-  return collapsed.length > CARD_SNIPPET_MAX ? `${collapsed.slice(0, CARD_SNIPPET_MAX)}…` : collapsed;
+  const collapsed = String(s || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return collapsed.length > CARD_SNIPPET_MAX
+    ? `${collapsed.slice(0, CARD_SNIPPET_MAX)}…`
+    : collapsed;
 }
 
 // One card per rule (not per occurrence) -- a rule with many occurrences of
@@ -185,7 +188,12 @@ function truncateForCard(s) {
 const MAX_CARDS = 24;
 
 function renderCards(checksResults) {
-  const withIssues = checksResults.filter((r) => (r.outcome === 'fail' || r.outcome === 'cantTell') && Array.isArray(r.occurrences) && r.occurrences.length > 0);
+  const withIssues = checksResults.filter(
+    (r) =>
+      (r.outcome === 'fail' || r.outcome === 'cantTell') &&
+      Array.isArray(r.occurrences) &&
+      r.occurrences.length > 0
+  );
   if (!withIssues.length) {
     return '<p class="note">No fail/cantTell rules with occurrences on this scan.</p>';
   }
@@ -196,15 +204,22 @@ function renderCards(checksResults) {
   });
   const shown = sorted.slice(0, MAX_CARDS);
 
-  const cards = shown.map((r) => {
-    const info = OUTCOME_INFO[r.outcome];
-    const occ = r.occurrences[0];
-    const wcagChips = ((r.meta && r.meta.normativeMappings) || [])
-      .map((m) => `<span class="chip" style="background:${STATUS.neutral.bg};color:${STATUS.neutral.color}">WCAG ${esc(m.requirement)}</span>`)
-      .join('');
-    const countLabel = r.occurrences.length > 1 ? ` <span class="card-count">× ${r.occurrences.length.toLocaleString()}</span>` : '';
-
-    return `<div class="card">
+  const cards = shown
+    .map((r) => {
+      const info = OUTCOME_INFO[r.outcome];
+      const occ = r.occurrences[0];
+      const wcagChips = ((r.meta && r.meta.normativeMappings) || [])
+        .map(
+          (m) =>
+            `<span class="chip" style="background:${STATUS.neutral.bg};color:${STATUS.neutral.color}">WCAG ${esc(m.requirement)}</span>`
+        )
+        .join('');
+      const countLabel =
+        r.occurrences.length > 1
+          ? ` <span class="card-count">× ${r.occurrences.length.toLocaleString()}</span>`
+          : '';
+
+      return `<div class="card">
       <div class="card-head">
         <span class="hero-legend-swatch" style="background:${info.color}">${info.icon}</span>
         <span class="card-title"><strong>${esc(r.ruleId)}</strong> (${esc(info.label)}, ${esc(r.severity)})${countLabel}</span>
@@ -216,11 +231,13 @@ function renderCards(checksResults) {
         ${r.occurrences.length > 1 ? `<p class="card-note">Selector/summary above are from one representative occurrence — ${r.occurrences.length.toLocaleString()} total on this rule.</p>` : ''}
       </div>
     </div>`;
-  }).join('\n');
+    })
+    .join('\n');
 
-  const overflow = sorted.length > MAX_CARDS
-    ? `<p class="note">Showing the ${MAX_CARDS} highest-priority rules of ${sorted.length.toLocaleString()} with issues — see the full technical data below for the rest.</p>`
-    : '';
+  const overflow =
+    sorted.length > MAX_CARDS
+      ? `<p class="note">Showing the ${MAX_CARDS} highest-priority rules of ${sorted.length.toLocaleString()} with issues — see the full technical data below for the rest.</p>`
+      : '';
 
   return `<div class="cards">${cards}</div>${overflow}`;
 }
@@ -251,7 +268,10 @@ function renderHtmlReport(result, options = {}) {
   const checksResults = Array.isArray(result && result.checksResults) ? result.checksResults : [];
   const rulesResults = Array.isArray(result && result.rulesResults) ? result.rulesResults : [];
   const byOutcome = countByOutcome(checksResults);
-  const generatedAtLabel = new Date().toLocaleString('en-US', { dateStyle: 'medium', timeStyle: 'medium' });
+  const generatedAtLabel = new Date().toLocaleString('en-US', {
+    dateStyle: 'medium',
+    timeStyle: 'medium'
+  });
   const title = (options && options.title) || 'surea11y scan report';
 
   const defaultOnList = OUTCOME_ORDER.filter((c) => OUTCOME_INFO[c].defaultOn);

package/src/sarif.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * Renders one scan result as a SARIF 2.1.0 log (docs/SARIF.md) for GitHub
+ * Code Scanning / other SARIF-consuming dashboards -- a different output
+ * shape from --json's raw result, purpose-built for that ecosystem (see
+ * docs/CLI.md's --sarif flag).
+ *
+ * Only fail/cantTell occurrences become SARIF results (a pass/notApplicable
+ * result has no occurrences at all -- see docs/OUTPUT_SCHEMA.md), the same
+ * "violations only" framing docs/REPORT.md's HTML report already uses.
+ * fail -> SARIF level "error" (the CI-gating case); cantTell -> "warning"
+ * (surfaced, non-blocking -- this engine's own cantTell/manual-review mental
+ * model, docs/TROUBLESHOOTING.md).
+ *
+ * If `baselineEntries` is supplied (mirrors --baseline, docs/BASELINE.md),
+ * fail occurrences already recorded there are omitted entirely rather than
+ * downgraded -- a generic SARIF consumer has no "known, don't re-gate"
+ * concept of its own, so the only faithful way to honor a baseline here is
+ * to not report the occurrence at all. cantTell occurrences are never
+ * baseline-filtered (the baseline mechanism only ever tracks fail
+ * occurrences, matching --write-baseline).
+ */
+
+const path = require('path');
+const { computeBaselineKey, getReasonCode } = require('./baseline.js');
+
+const SARIF_SCHEMA_URI =
+  'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/Schemata/sarif-schema-2.1.0.json';
+const SARIF_VERSION = '2.1.0';
+
+function artifactUriFromResult(result) {
+  const url = result && result.url;
+  if (!url) return 'about:blank';
+  if (url.startsWith('file://')) {
+    const filePath = url.slice('file://'.length);
+    const rel = path.relative(process.cwd(), filePath).split(path.sep).join('/');
+    // A file outside the cwd (e.g. an absolute path elsewhere on disk)
+    // produces a "../"-leading relative path -- still valid as a URI, just
+    // not resolvable as a repo-relative one by a SARIF consumer like GitHub
+    // Code Scanning (see docs/SARIF.md's known limitations).
+    return rel || filePath;
+  }
+  return url;
+}
+
+function buildRemainingBaselineMap(baselineEntries) {
+  const remaining = new Map();
+  for (const entry of Array.isArray(baselineEntries) ? baselineEntries : []) {
+    if (!entry) continue;
+    const key = computeBaselineKey(
+      entry.ruleId,
+      entry.reasonCode || 'DEFAULT',
+      typeof entry.html === 'string' ? entry.html : ''
+    );
+    remaining.set(key, (remaining.get(key) || 0) + 1);
+  }
+  return remaining;
+}
+
+function wcagTags(check) {
+  const mappings = (check.meta && check.meta.normativeMappings) || [];
+  const tags = new Set(['accessibility', check.type === 'automatic' ? 'automatic' : 'manual']);
+  for (const m of mappings) {
+    if (m && m.requirement) tags.add(`wcag-${m.requirement}`);
+  }
+  return Array.from(tags);
+}
+
+function buildRule(check) {
+  return {
+    id: check.ruleId,
+    name: check.ruleId,
+    shortDescription: { text: check.title || check.ruleId },
+    fullDescription: { text: check.description || check.title || check.ruleId },
+    // type: "manual" rules are capped at cantTell (never fail), so their
+    // worst-case, rule-level default is "warning"; automatic rules can
+    // reach "error" -- see docs/OUTPUT_SCHEMA.md's outcome/type table.
+    defaultConfiguration: { level: check.type === 'automatic' ? 'error' : 'warning' },
+    properties: { tags: wcagTags(check) }
+  };
+}
+
+function buildResult(check, occurrence, level, artifactUri) {
+  const reasonCode = getReasonCode(occurrence);
+  const html = typeof occurrence.html === 'string' ? occurrence.html : '';
+  const message = occurrence.hint ? `${occurrence.summary} ${occurrence.hint}` : occurrence.summary;
+
+  return {
+    ruleId: check.ruleId,
+    level,
+    message: { text: message },
+    locations: [
+      {
+        physicalLocation: { artifactLocation: { uri: artifactUri } },
+        ...(occurrence.selector
+          ? { logicalLocations: [{ fullyQualifiedName: occurrence.selector, kind: 'element' }] }
+          : {})
+      }
+    ],
+    partialFingerprints: {
+      'surea11y/violation/v1': computeBaselineKey(check.ruleId, reasonCode, html)
+    },
+    properties: {
+      severity: check.severity,
+      confidence: check.confidence,
+      reasonCode,
+      html
+    }
+  };
+}
+
+function renderSarifReport(result, options = {}) {
+  const { toolVersion, informationUri, baselineEntries } = options;
+  const artifactUri = artifactUriFromResult(result);
+  const remaining = buildRemainingBaselineMap(baselineEntries);
+
+  const rules = [];
+  const seenRuleIds = new Set();
+  const failResults = [];
+  const cantTellResults = [];
+
+  for (const check of (result && result.checksResults) || []) {
+    if (!check || !Array.isArray(check.occurrences)) continue;
+
+    if (!seenRuleIds.has(check.ruleId)) {
+      seenRuleIds.add(check.ruleId);
+      rules.push(buildRule(check));
+    }
+
+    if (check.outcome !== 'fail' && check.outcome !== 'cantTell') continue;
+
+    for (const occurrence of check.occurrences) {
+      if (!occurrence) continue;
+
+      if (check.outcome === 'fail') {
+        const reasonCode = getReasonCode(occurrence);
+        const html = typeof occurrence.html === 'string' ? occurrence.html : '';
+        const key = computeBaselineKey(check.ruleId, reasonCode, html);
+        const left = remaining.get(key) || 0;
+        if (left > 0) {
+          remaining.set(key, left - 1);
+          continue; // already known via the baseline -- omit, don't re-gate
+        }
+        failResults.push(buildResult(check, occurrence, 'error', artifactUri));
+      } else {
+        cantTellResults.push(buildResult(check, occurrence, 'warning', artifactUri));
+      }
+    }
+  }
+
+  const sarifLog = {
+    $schema: SARIF_SCHEMA_URI,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'surea11y',
+            informationUri: informationUri || 'https://github.com/rumoroso/surea11y-core',
+            version: toolVersion || '0.0.0',
+            rules
+          }
+        },
+        // fail first: matches docs/REPORT.md's own "violations before advisory
+        // findings" ordering.
+        results: [...failResults, ...cantTellResults]
+      }
+    ]
+  };
+
+  return JSON.stringify(sarifLog, null, 2) + '\n';
+}
+
+module.exports = { renderSarifReport };