Axe Plugin - Category Aggregation #1139

User story

As a Code PushUp user, I want to aggregate accessibility metrics into a single category that combines results from the Axe plugin, so that I can track overall accessibility compliance across my application.

Scenarios:

1. Auto-generated from preset: the plugin automatically creates an accessibility category from the groups analyzed as part of the chosen preset.
2. Custom composition: a user manually composes a category using specific Axe groups and audits with granular control.
3. Multi-URL support: a user runs accessibility checks on multiple URLs, and the category configuration automatically expands for each URL.
4. Discoverability: when a user creates a custom category, helper functions ensure only valid Axe group slugs can be passed in.
5. Validation: if a group or audit that wasn't analyzed (because it's not in the selected preset) is referenced, a user receives a clear error message explaining which reference is invalid and which groups are available.

Context

Multi-URL handling logic is extracted to shared utilities as part of #1134. It provides the foundation for category aggregation in both scenarios.

This implementation follows mergeLighthouseCategories pattern and reuses helpers from plugin-url-aggregation.ts.

Related discussion: #1135

Acceptance criteria

• Users can auto-generate an accessibility category using axeCategories(plugin) helper
• Users can provide custom categories that get properly expanded for multi-URL: axeCategories(plugin, categories)
• Users can discover valid Axe group slugs via an exported AxeGroupSlug type
• Helper functions are provided for creating category refs (e.g., axeGroupRef, axeAuditRef)
• Error messages clearly indicate which reference is invalid and list available groups from the current preset
• Both auto-generated and custom approaches work seamlessly with multi-URL configurations
• README demonstrates usage patterns
• Documentation includes examples for both auto-generated and custom composition
• Tests cover single-URL and multi-URL scenarios for both approaches

Implementation details

Single-plugin categories

1. Expose types and helpers for discoverability:

export type AxeGroupSlug = 'aria' | 'color' | ...;

export function axeGroupRef(slug: AxeGroupSlug, weight?: number): CategoryRef;
export function axeAuditRef(slug: string, weight?: number): CategoryRef;

2. Provide category merging helper with validation:

/**
 * Auto-generates accessibility category from ALL groups in the plugin (if no categories provided),
 * or expands user-provided categories for multi-URL runs.
 *
 * Validates that all referenced groups/audits exist in the plugin configuration.
 * Throws descriptive error if invalid references are found.
 */
export function axeCategories(
  plugin: Pick<PluginConfig, 'groups' | 'context'>,
  categories?: CategoryConfig[],
): CategoryConfig[];

3. Update preset and docs to demonstrate usage:

import axePlugin, {
  axeCategories,
  axeGroupRef,
} from './packages/plugin-axe/src/index.js';

const axe = axePlugin(urls, { preset: 'wcag21aa' });

// Option 1: Auto-generated (recommended for most users)
// Creates category from ALL groups in the selected preset
export default {
  plugins: [axe],
  categories: axeCategories(axe),
  // ...
};

// Option 2: Custom composition with granular control
// Reference specific groups from the selected preset
export default {
  plugins: [axe],
  categories: mergeAxeCategories(axe, [
    {
      slug: 'accessibility',
      title: 'Accessibility',
      refs: [axeGroupRef('aria', 2), axeGroupRef('color')],
    },
  ]),
};