feat(utils,plugin-axe): improve report formatting

Author: hanna-skryl

packages/plugin-axe/src/lib/runner/transform.ts

@@ -1,4 +1,5 @@
 import type { AxeResults, ImpactValue, NodeResult, Result } from 'axe-core';
+import type axe from 'axe-core';
 import type {
   AuditOutput,
   AuditOutputs,
@@ -75,8 +76,15 @@ function formatSeverityCounts(issues: Issue[]): string {
     .join(', ');
 }
 
+function formatSelector(selector: axe.CrossTreeSelector): string {
+  if (typeof selector === 'string') {
+    return selector;
+  }
+  return selector.join(' >> ');
+}
+
 function toIssue(node: NodeResult, result: Result, url: string): Issue {
-  const selector = node.target?.[0] || node.html;
+  const selector = formatSelector(node.target?.[0] || node.html);
   const rawMessage = node.failureSummary || result.help;
   const cleanedMessage = rawMessage.replace(/\s+/g, ' ').trim();
 

packages/plugin-axe/src/lib/runner/transform.unit.test.ts

@@ -228,4 +228,71 @@ describe('toAuditOutputs', () => {
       displayValue: '2 errors, 1 warning, 1 info',
     });
   });
+
+  it('should format shadow DOM selectors with >> notation', () => {
+    const results = createMockAxeResults({
+      violations: [
+        createMockResult('color-contrast', [
+          createMockNode({
+            html: '<button></button>',
+            target: [['#app', 'my-component', 'button']],
+            impact: 'critical',
+            failureSummary: 'Fix this: Element has insufficient color contrast',
+          }),
+        ]),
+      ],
+    });
+
+    expect(toAuditOutputs(results, testUrl)).toEqual<AuditOutput[]>([
+      {
+        slug: 'color-contrast',
+        score: 0,
+        value: 1,
+        displayValue: '1 error',
+        details: {
+          issues: [
+            {
+              message:
+                '[#app >> my-component >> button] Fix this: Element has insufficient color contrast (https://example.com)',
+              severity: 'error',
+            },
+          ],
+        },
+      },
+    ]);
+  });
+
+  it('should fall back to html when target is missing', () => {
+    const results = createMockAxeResults({
+      violations: [
+        createMockResult('aria-roles', [
+          createMockNode({
+            html: '<div role="invalid-role">Content</div>',
+            target: undefined,
+            impact: 'serious',
+            failureSummary:
+              'Fix this: Ensure all values assigned to role="" correspond to valid ARIA roles',
+          }),
+        ]),
+      ],
+    });
+
+    expect(toAuditOutputs(results, testUrl)).toEqual<AuditOutput[]>([
+      {
+        slug: 'aria-roles',
+        score: 0,
+        value: 1,
+        displayValue: '1 error',
+        details: {
+          issues: [
+            {
+              message:
+                '[<div role="invalid-role">Content</div>] Fix this: Ensure all values assigned to role="" correspond to valid ARIA roles (https://example.com)',
+              severity: 'error',
+            },
+          ],
+        },
+      },
+    ]);
+  });
 });

packages/utils/src/lib/reports/formatting.ts

@@ -73,13 +73,14 @@ export function metaDescription(
     if (!description) {
       return docsLink;
     }
-    const parsedDescription = description.endsWith('```')
-      ? `${description}\n\n`
-      : `${description} `;
+    const formattedDescription = wrapTags(description);
+    const parsedDescription = formattedDescription.endsWith('```')
+      ? `${formattedDescription}\n\n`
+      : `${formattedDescription} `;
     return md`${parsedDescription}${docsLink}`;
   }
   if (description && description.trim().length > 0) {
-    return description;
+    return wrapTags(description);
   }
   return '';
 }
@@ -171,3 +172,14 @@ export function formatFileLink(
       return relativePath;
   }
 }
+
+/**
+ * Wraps HTML tags in backticks to prevent markdown parsers
+ * from interpreting them as actual HTML.
+ */
+export function wrapTags(text?: string): string {
+  if (!text) {
+    return '';
+  }
+  return text.replace(/<[a-z][a-z0-9]*[^>]*>/gi, '`$&`');
+}

packages/utils/src/lib/reports/formatting.unit.test.ts

@@ -8,6 +8,7 @@ import {
   linkToLocalSourceForIde,
   metaDescription,
   tableSection,
+  wrapTags,
 } from './formatting.js';
 
 describe('tableSection', () => {
@@ -360,3 +361,21 @@ describe('formatFileLink', () => {
     ).toBe('../src/index.ts');
   });
 });
+
+describe('wrapTags', () => {
+  it.each([
+    ['<label>', '`<label>`'],
+    ['<img src="test.jpg">', '`<img src="test.jpg">`'],
+    [
+      '<li> elements must be contained in a <ul> or <ol>',
+      '`<li>` elements must be contained in a `<ul>` or `<ol>`',
+    ],
+    ['x < 5', 'x < 5'],
+    ['x < 5 and y > 3', 'x < 5 and y > 3'],
+    ['body > button', 'body > button'],
+    ['', ''],
+    [undefined, ''],
+  ])('should transform %j to %j', (input, expected) => {
+    expect(wrapTags(input)).toBe(expected);
+  });
+});

packages/utils/src/lib/reports/generate-md-report-category-section.ts

@@ -2,7 +2,7 @@ import { type InlineText, MarkdownDocument, md } from 'build-md';
 import type { AuditReport } from '@code-pushup/models';
 import { slugify } from '../formatting.js';
 import { HIERARCHY } from '../text-formats/index.js';
-import { metaDescription } from './formatting.js';
+import { metaDescription, wrapTags } from './formatting.js';
 import { getSortableAuditByRef, getSortableGroupByRef } from './sorting.js';
 import type { ScoreFilter, ScoredGroup, ScoredReport } from './types.js';
 import {
@@ -90,7 +90,7 @@ export function categoryRef(
 ): InlineText {
   const auditTitleAsLink = md.link(
     `#${slugify(title)}-${slugify(pluginTitle)}`,
-    title,
+    wrapTags(title),
   );
   const marker = scoreMarker(score, 'square');
   return md`${marker} ${auditTitleAsLink} (${md.italic(

packages/utils/src/lib/reports/generate-md-report.ts

@@ -14,6 +14,7 @@ import {
   metaDescription,
   tableSection,
   treeSection,
+  wrapTags,
 } from './formatting.js';
 import {
   categoriesDetailsSection,
@@ -86,16 +87,17 @@ export function auditDetailsIssues(
       ],
       issues.map(({ severity: level, message, source }: Issue) => {
         const severity = md`${severityMarker(level)} ${md.italic(level)}`;
+        const formattedMessage = wrapTags(message);
 
         if (!source) {
-          return [severity, message];
+          return [severity, formattedMessage];
         }
         const file = linkToLocalSourceForIde(source, options);
         if (!source.position) {
-          return [severity, message, file];
+          return [severity, formattedMessage, file];
         }
         const line = formatSourceLine(source.position);
-        return [severity, message, file, line];
+        return [severity, formattedMessage, file, line];
       }),
     );
 }
@@ -143,7 +145,7 @@ export function auditsSection(
           .map(audit => ({ ...audit, plugin })),
       ),
       (doc, { plugin, ...audit }) => {
-        const auditTitle = `${audit.title} (${plugin.title})`;
+        const auditTitle = `${wrapTags(audit.title)} (${plugin.title})`;
         const detailsContent = auditDetails(audit, options);
         const descriptionContent = metaDescription(audit);