@surea11y/core 1.2.0 → 1.4.0

package/src/index.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 // surea11y public API: export the generated core surface verbatim

package/src/report.js

@@ -1,23 +1,18 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * 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 +21,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 +34,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,
@@ -61,6 +58,32 @@ function countByOutcome(checksResults) {
   return counts;
 }
 
+function getOccurrenceOutcome(ruleResult, occurrence) {
+  const occurrenceOutcome =
+    occurrence &&
+    (occurrence.occurrenceOutcome === 'fail' || occurrence.occurrenceOutcome === 'cantTell'
+      ? occurrence.occurrenceOutcome
+      : occurrence.outcome === 'fail' || occurrence.outcome === 'cantTell'
+        ? occurrence.outcome
+        : null);
+  if (occurrenceOutcome) return occurrenceOutcome;
+  return (
+    ruleResult &&
+    (ruleResult.outcome === 'fail' || ruleResult.outcome === 'cantTell' ? ruleResult.outcome : null)
+  );
+}
+
+function getCardOutcome(ruleResult) {
+  if (!ruleResult || !Array.isArray(ruleResult.occurrences)) return ruleResult.outcome;
+  let hasCantTell = false;
+  for (const occ of ruleResult.occurrences) {
+    const outcome = getOccurrenceOutcome(ruleResult, occ);
+    if (outcome === 'fail') return 'fail';
+    if (outcome === 'cantTell') hasCantTell = true;
+  }
+  return hasCantTell ? 'cantTell' : ruleResult.outcome;
+}
+
 // One plain-language headline + one horizontal stacked bar + a legend with
 // icon+label+count (status color is never the only signal) -- the first
 // thing a reader sees; exhaustive detail lives in the collapsed
@@ -69,8 +92,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 +101,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 +154,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 +164,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 +203,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,42 +216,69 @@ 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) =>
+      Array.isArray(r.occurrences) &&
+      r.occurrences.some((occ) => {
+        const outcome = getOccurrenceOutcome(r, occ);
+        return outcome === 'fail' || outcome === 'cantTell';
+      })
+  );
   if (!withIssues.length) {
     return '<p class="note">No fail/cantTell rules with occurrences on this scan.</p>';
   }
 
   const sorted = withIssues.slice().sort((a, b) => {
-    if (a.outcome !== b.outcome) return a.outcome === 'fail' ? -1 : 1;
+    const aOutcome = getCardOutcome(a);
+    const bOutcome = getCardOutcome(b);
+    if (aOutcome !== bOutcome) return aOutcome === 'fail' ? -1 : 1;
     return b.occurrences.length - a.occurrences.length;
   });
   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 cardOutcome = getCardOutcome(r);
+      const info = OUTCOME_INFO[cardOutcome] || OUTCOME_INFO.notApplicable;
+      const occurrenceCounts = { fail: 0, cantTell: 0 };
+      for (const occ of r.occurrences) {
+        const outcome = getOccurrenceOutcome(r, occ);
+        if (outcome === 'fail' || outcome === 'cantTell') occurrenceCounts[outcome] += 1;
+      }
+      const representative =
+        r.occurrences.find((occ) => getOccurrenceOutcome(r, occ) === cardOutcome) ||
+        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 hasMixedOutcomes = occurrenceCounts.fail > 0 && occurrenceCounts.cantTell > 0;
+      const countLabel =
+        r.occurrences.length > 1
+          ? ` <span class="card-count">× ${r.occurrences.length.toLocaleString()}${hasMixedOutcomes ? ` (${occurrenceCounts.fail.toLocaleString()} fail / ${occurrenceCounts.cantTell.toLocaleString()} needs review)` : ''}</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>
       </div>
       <div class="card-body">
         <div class="card-meta">${wcagChips}</div>
-        <div class="card-selector"><span class="card-selector-label">Selector:</span> <code>${esc(occ.selector || '(none)')}</code></div>
-        <div class="card-snippet">${esc(occ.summary)}${occ.hint ? ` — ${esc(occ.hint)}` : ''}</div>
+        <div class="card-selector"><span class="card-selector-label">Selector:</span> <code>${esc(representative.selector || '(none)')}</code></div>
+        <div class="card-snippet">${esc(representative.summary)}${representative.hint ? ` — ${esc(representative.hint)}` : ''}</div>
         ${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}`;
 }
@@ -233,9 +291,10 @@ function flattenOccurrences(checksResults) {
   for (const r of checksResults) {
     if (!Array.isArray(r.occurrences)) continue;
     for (const occ of r.occurrences) {
+      const occurrenceOutcome = getOccurrenceOutcome(r, occ);
       rows.push({
         ruleId: r.ruleId,
-        outcome: r.outcome,
+        outcome: occurrenceOutcome || r.outcome,
         severity: r.severity,
         selector: occ.selector || '',
         html: occ.html || '',
@@ -251,7 +310,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,190 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'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 getOccurrenceOutcome(check, occurrence) {
+  const occurrenceOutcome =
+    occurrence &&
+    (occurrence.occurrenceOutcome === 'fail' || occurrence.occurrenceOutcome === 'cantTell'
+      ? occurrence.occurrenceOutcome
+      : occurrence.outcome === 'fail' || occurrence.outcome === 'cantTell'
+        ? occurrence.outcome
+        : null);
+  if (occurrenceOutcome) return occurrenceOutcome;
+  return check && (check.outcome === 'fail' || check.outcome === 'cantTell') ? check.outcome : null;
+}
+
+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;
+
+      const occurrenceOutcome = getOccurrenceOutcome(check, occurrence);
+      if (occurrenceOutcome === '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 if (occurrenceOutcome === 'cantTell') {
+        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/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 };