Multi-URL aware helpers for cross-plugin composition

[hanna-skryl]

User story

As a Code PushUp user, I want a single utility to compose a category from multiple plugins.

Scenarios

1. Single plugin category: User creates a category from one plugin's groups/audits.
2. Multi-plugin category: User combines refs from multiple plugins (e.g., Lighthouse + Axe for accessibility).
3. Multi-URL transparency: Refs automatically expand for plugins with multi-URL configs; single-URL plugins work unchanged.
4. Mixed plugins: Some plugins have multi-URL, others don't; each expands according to its own context.

Acceptance criteria

• Plugin-specific ref helpers handle multi-URL expansion (lighthouseGroupRefs, axeGroupRefs, etc.)
• Helpers accept optional slug parameter (all groups when omitted, specific group when provided)
• Helpers accept optional weight parameter
• Refs can be combined from multiple plugins in a single category
• Single-URL configs work unchanged (no expansion needed)
• Documentation with examples
• Deprecated old helpers (lighthouseCategories, axeCategories, singular ref helpers)

Implementation details

// Lighthouse helpers
lighthouseGroupRefs(plugin, groupSlug?, weight?): CategoryRef[]
lighthouseAuditRefs(plugin, auditSlug?, weight?): CategoryRef[]

// Axe helpers
axeGroupRefs(plugin, groupSlug?, weight?): CategoryRef[]
axeAuditRefs(plugin, auditSlug?, weight?): CategoryRef[]

// Utils (internal)
expandCategoryRefs(ref, context): CategoryRef[]

Usage examples:

import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';
import lighthousePlugin, { lighthouseGroupRefs } from '@code-pushup/lighthouse-plugin';

const urls = ['https://example.com', 'https://example.com/about'];
const axe = axePlugin(urls);
const lighthouse = await lighthousePlugin(urls);

// Single plugin - all groups
categories: [
  {
    slug: 'a11y',
    title: 'Accessibility',
    refs: axeGroupRefs(axe),
  },
];

// Single plugin - specific group
categories: [
  {
    slug: 'performance',
    title: 'Performance',
    refs: lighthouseGroupRefs(lighthouse, 'performance'),
  },
];

// Multi-plugin composition
categories: [
  {
    slug: 'a11y',
    title: 'Accessibility',
    refs: [...lighthouseGroupRefs(lighthouse, 'accessibility'), ...axeGroupRefs(axe)],
  },
];

// Cherry-picked refs with custom weights
categories: [
  {
    slug: 'a11y',
    title: 'Accessibility',
    refs: [...axeGroupRefs(axe, 'aria', 2), ...axeGroupRefs(axe, 'color'), ...lighthouseGroupRefs(lighthouse, 'accessibility')],
  },
];