Merge pull request #154 from mgifford/copilot/add-unique-identifier-to-reports

Add stable unique identifiers (DAP-xxxxxxxx) to axe accessibility findings

Author: mgifford

src/publish/render-pages.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { AXE_TO_FPC, FPC_LABELS, FPC_SVGS, FPC_DESCRIPTIONS } from '../data/axe-fpc-mapping.js';
 import { getFpcPrevalenceRates, CENSUS_DISABILITY_STATS } from '../data/census-disability-stats.js';
 import { getPolicyNarrative, getHeuristicsForAxeRule } from '../data/axe-impact-loader.js';
@@ -23,6 +24,30 @@ function formatCompact(n) {
   return String(n);
 }
 
+/**
+ * Generates a stable unique identifier for an accessibility violation.
+ * The ID is based on the normalized URL, rule ID, and element selector so that
+ * the same violation on the same element produces the same ID across scans,
+ * enabling tracking of how long an issue has persisted.
+ *
+ * @param {string} pageUrl - The URL of the scanned page
+ * @param {string} ruleId  - The axe rule ID (e.g. "color-contrast")
+ * @param {string} [selector] - The CSS selector of the affected element (empty string for finding-level ID)
+ * @returns {string} A short stable identifier, e.g. "DAP-a1b2c3d4"
+ */
+export function generateViolationId(pageUrl, ruleId, selector = '') {
+  const safeUrl = typeof pageUrl === 'string' ? pageUrl : '';
+  const safeRuleId = typeof ruleId === 'string' ? ruleId : '';
+  const safeSelector = typeof selector === 'string' ? selector : '';
+  const normalizedUrl = safeUrl
+    .replace(/^https?:\/\//i, '')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+  const seed = `${normalizedUrl}|${safeRuleId}|${safeSelector}`;
+  const hash = createHash('sha256').update(seed).digest('hex').slice(0, 8);
+  return `DAP-${hash}`;
+}
+
 /**
  * Format a byte count as a human-readable string (B / KB / MB / GB).
  *
@@ -606,6 +631,17 @@ function renderSharedStyles() {
       overflow-x: auto;
       font-size: 0.85em;
     }
+    .violation-id {
+      font-size: 0.75em;
+      font-family: monospace;
+      color: var(--color-muted, #6b7280);
+      background: var(--color-code-bg, #f3f4f6);
+      border: 1px solid var(--color-border, #d1d5db);
+      border-radius: 3px;
+      padding: 0.1em 0.35em;
+      vertical-align: middle;
+      user-select: all;
+    }
     .finding-detail {
       padding: 0.5rem 1rem;
       border: 1px solid var(--color-finding-border);
@@ -1794,21 +1830,26 @@ function renderWcagTags(tags = []) {
   return `<p class="wcag-tags"><strong>WCAG criteria:</strong> ${wcagLabels.map((l) => escapeHtml(l)).join(', ')}</p>`;
 }
 
-function renderAxeFindingItems(items = []) {
+function renderAxeFindingItems(items = [], pageUrl = '', ruleId = '') {
   if (items.length === 0) {
     return '<p><em>No specific element details available.</em></p>';
   }
 
   return items
     .map(
-      (item, index) => `
+      (item, index) => {
+        const elementId = typeof pageUrl === 'string' && pageUrl.length > 0 && typeof ruleId === 'string' && ruleId.length > 0
+          ? generateViolationId(pageUrl, ruleId, item.selector ?? '')
+          : '';
+        return `
       <div class="axe-item">
-        <p><strong>Element ${index + 1}</strong></p>
+        <p><strong>Element ${index + 1}</strong>${elementId ? ` <code class="violation-id" title="Stable identifier for this accessibility violation">${escapeHtml(elementId)}</code>` : ''}</p>
         ${item.selector ? `<p><strong>Element path:</strong> <code>${escapeHtml(item.selector)}</code></p>` : ''}
         ${item.snippet ? `<p><strong>Snippet:</strong></p><pre><code>${escapeHtml(item.snippet)}</code></pre>` : ''}
         ${item.node_label && item.node_label !== item.selector ? `<p><strong>Label:</strong> ${escapeHtml(item.node_label)}</p>` : ''}
         ${renderExplanationHtml(item.explanation)}
-      </div>`
+      </div>`;
+      }
     )
     .join('\n');
 }
@@ -1853,10 +1894,12 @@ function formatImpactList(items) {
 export function buildFindingCopyText(pageUrl, finding, pageLoadCount = 0, scanDate = '') {
   const wcagLabels = (finding.tags ?? []).map(formatWcagTag).filter(Boolean);
   const fpcCodes = AXE_TO_FPC.get(finding.id) ?? [];
+  const findingId = generateViolationId(pageUrl, finding.id, '');
   const lines = [
     `**URL:** ${pageUrl}`,
     '',
     `**${finding.title}** (rule: \`${finding.id}\`)`,
+    `**Violation ID:** ${findingId}`,
     '',
     plainTextDescription(finding.description ?? ''),
   ];
@@ -1891,7 +1934,8 @@ export function buildFindingCopyText(pageUrl, finding, pageLoadCount = 0, scanDa
   lines.push('', `**Affected elements (${items.length}):**`);
 
   items.forEach((item, index) => {
-    lines.push('', `**Element ${index + 1}**`);
+    const elementId = generateViolationId(pageUrl, finding.id, item.selector ?? '');
+    lines.push('', `**Element ${index + 1}** (ID: ${elementId})`);
     if (item.selector) {
       lines.push(`Element path: \`${item.selector}\``);
     }
@@ -1922,15 +1966,16 @@ function renderAxeFindingsList(axeFindings = [], pageUrl = '', pageLoadCount = 0
         fpcCodes && fpcCodes.length > 0
           ? `<p><strong>Disabilities affected:</strong> ${renderFpcCodes(finding.id, pageLoadCount, prevalenceRates)}</p>`
           : '';
+      const findingId = generateViolationId(pageUrl, finding.id, '');
       return `
       <details>
-        <summary><strong>${escapeHtml(finding.title)}</strong> (rule: <code>${escapeHtml(finding.id)}</code>)</summary>
+        <summary><strong>${escapeHtml(finding.title)}</strong> (rule: <code>${escapeHtml(finding.id)}</code>) <code class="violation-id" title="Stable identifier for this accessibility finding">${escapeHtml(findingId)}</code></summary>
         <div class="finding-detail">
           <p>${renderDescriptionHtml(finding.description)}</p>
           ${renderWcagTags(finding.tags)}
           ${fpcHtml}
           <p><strong>Affected elements (${finding.items.length}):</strong></p>
-          ${renderAxeFindingItems(finding.items)}
+          ${renderAxeFindingItems(finding.items, pageUrl, finding.id)}
           <button class="copy-finding-btn" data-copy-text="${escapeHtml(buildFindingCopyText(pageUrl, finding, pageLoadCount, scanDate))}" aria-label="Copy finding to clipboard">Copy finding</button>
         </div>
       </details>`;

tests/unit/render-pages.test.js

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { renderDailyReportPage, renderDashboardPage, renderArchiveIndexPage, renderArchiveRedirectStub, render404Page, renderCodeQualityPage, buildFindingCopyText, plainTextDescription, buildUsabilityHeuristicsCounts } from '../../src/publish/render-pages.js';
+import { renderDailyReportPage, renderDashboardPage, renderArchiveIndexPage, renderArchiveRedirectStub, render404Page, renderCodeQualityPage, buildFindingCopyText, plainTextDescription, buildUsabilityHeuristicsCounts, generateViolationId } from '../../src/publish/render-pages.js';
 import { renderFailurePage } from '../../src/publish/failure-report.js';
 
 test('renderDailyReportPage filters out zero-score history entries', () => {
@@ -741,6 +741,48 @@ test('plainTextDescription converts markdown links to plain text', () => {
   assert.ok(!result.includes('[Learn more]'), 'Should not contain raw markdown link syntax');
 });
 
+test('generateViolationId returns a stable DAP- prefixed identifier', () => {
+  const id = generateViolationId('https://fdic.gov', 'tabindex', 'body.acquia-cms-toolbar > a.skipheader');
+  assert.ok(id.startsWith('DAP-'), 'Should have DAP- prefix');
+  assert.match(id, /^DAP-[0-9a-f]{8}$/, 'Should be DAP- followed by 8 hex characters');
+});
+
+test('generateViolationId produces the same ID for the same inputs', () => {
+  const id1 = generateViolationId('https://fdic.gov', 'tabindex', 'body > a.skip');
+  const id2 = generateViolationId('https://fdic.gov', 'tabindex', 'body > a.skip');
+  assert.equal(id1, id2, 'Same inputs should produce the same ID');
+});
+
+test('generateViolationId produces different IDs for different selectors', () => {
+  const id1 = generateViolationId('https://fdic.gov', 'tabindex', 'body > a.skip');
+  const id2 = generateViolationId('https://fdic.gov', 'tabindex', 'div > button#other');
+  assert.notEqual(id1, id2, 'Different selectors should produce different IDs');
+});
+
+test('generateViolationId produces different IDs for different rule IDs', () => {
+  const id1 = generateViolationId('https://fdic.gov', 'tabindex', 'body > a.skip');
+  const id2 = generateViolationId('https://fdic.gov', 'color-contrast', 'body > a.skip');
+  assert.notEqual(id1, id2, 'Different rule IDs should produce different IDs');
+});
+
+test('generateViolationId normalizes URL protocol and trailing slash', () => {
+  const id1 = generateViolationId('https://fdic.gov', 'tabindex', 'a.skip');
+  const id2 = generateViolationId('http://fdic.gov/', 'tabindex', 'a.skip');
+  assert.equal(id1, id2, 'http/https and trailing slash differences should not affect the ID');
+});
+
+test('generateViolationId produces finding-level ID when selector is empty', () => {
+  const id = generateViolationId('https://fdic.gov', 'tabindex', '');
+  assert.ok(id.startsWith('DAP-'), 'Finding-level ID should have DAP- prefix');
+  assert.match(id, /^DAP-[0-9a-f]{8}$/, 'Should be DAP- followed by 8 hex characters');
+});
+
+test('generateViolationId handles non-string inputs gracefully', () => {
+  const id = generateViolationId(null, undefined, 42);
+  assert.ok(id.startsWith('DAP-'), 'Should still return a DAP-prefixed ID with non-string inputs');
+  assert.match(id, /^DAP-[0-9a-f]{8}$/, 'Should be DAP- followed by 8 hex characters');
+});
+
 test('buildFindingCopyText includes page URL and finding details', () => {
   const pageUrl = 'https://informeddelivery.usps.com';
   const finding = {
@@ -769,6 +811,8 @@ test('buildFindingCopyText includes page URL and finding details', () => {
   assert.ok(text.includes('<h4>'), 'Should include element snippet');
   assert.ok(text.includes('What is Informed Delivery?'), 'Should include node label');
   assert.ok(text.includes('Heading order invalid'), 'Should include how-to-fix text');
+  assert.ok(text.includes('**Violation ID:** DAP-'), 'Should include a finding-level violation ID');
+  assert.ok(text.includes('(ID: DAP-'), 'Should include an element-level violation ID');
 });
 
 test('buildFindingCopyText handles finding with no items', () => {