Axe Plugin - Category Aggregation

[hanna-skryl]

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.

Related discussion: #1135

Acceptance criteria

• [ ] Users can auto-generate an accessibility category using mergeAxeGroupRefs(plugin) helper
• [ ] Users can provide custom categories that get properly expanded for multi-URL: mergeAxeGroupRefs(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
• [ ] The Axe preset demonstrates category usage with mergeAxeGroupRefs
• [ ] 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 = 'wcag21-level-a' | ... | '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 mergeAxeGroupRefs(
  plugin: PluginConfig,
  categories?: CategoryConfig[],
): CategoryConfig;

3. Update preset and docs to demonstrate usage:

import axePlugin, {
  axeGroupRef,
  mergeAxeGroupRefs,
} 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
const accessibilityCategory = mergeAxeGroupRefs(axe);

export default {
  plugins: [axe],
  categories: [accessibilityCategory],
  // ...
};

// Option 2: Custom composition with granular control
// Reference specific groups from the selected preset
const customCategory = mergeAxeGroupRefs(axe, [
  {
    slug: 'accessibility',
    title: 'Accessibility',
    refs: [
      axeGroupRef('wcag22-level-a'),
      axeGroupRef('wcag22-level-aa'),
    ]
  }
])

export default {
  plugins: [axe],
  categories: [customCategory],
  // ...
};