@code-pushup/axe-plugin 0.95.2 → 0.96.0

package/README.md

@@ -159,6 +159,66 @@ The plugin organizes audits into category groups based on axe-core's accessibili
 
 Use `npx code-pushup print-config --onlyPlugins=axe` to list all audits and groups for your configuration.
 
+## Category integration
+
+The plugin provides helpers to integrate Axe results into your categories.
+
+### Auto-generate accessibility category
+
+Use `axeCategories` to automatically create an accessibility category from all plugin groups:
+
+```ts
+import axePlugin, { axeCategories } from '@code-pushup/axe-plugin';
+
+const axe = axePlugin('https://example.com');
+
+export default {
+  plugins: [axe],
+  categories: axeCategories(axe),
+};
+```
+
+This configuration works with both single-URL and multi-URL configurations. For multi-URL setups, refs are automatically expanded for each URL with appropriate weights.
+
+### Custom categories
+
+For fine-grained control, provide your own categories with specific groups:
+
+```ts
+import axePlugin, { axeCategories, axeGroupRef } from '@code-pushup/axe-plugin';
+
+const axe = axePlugin(['https://example.com', 'https://example.com/about']);
+
+export default {
+  plugins: [axe],
+  categories: axeCategories(axe, [
+    {
+      slug: 'axe-a11y',
+      title: 'Axe Accessibility',
+      refs: [axeGroupRef('aria', 2), axeGroupRef('color'), axeGroupRef('keyboard')],
+    },
+  ]),
+};
+```
+
+### Helper functions
+
+| Function        | Description                            |
+| --------------- | -------------------------------------- |
+| `axeCategories` | Auto-generates or expands categories   |
+| `axeGroupRef`   | Creates a category ref to an Axe group |
+| `axeAuditRef`   | Creates a category ref to an Axe audit |
+
+### Type safety
+
+The `AxeGroupSlug` type is exported for discovering valid group slugs:
+
+```ts
+import type { AxeGroupSlug } from '@code-pushup/axe-plugin';
+
+const group: AxeGroupSlug = 'aria';
+```
+
 ## Resources
 
 - **[Axe-core rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)** - Complete list of accessibility rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-pushup/axe-plugin",
-  "version": "0.95.2",
+  "version": "0.96.0",
   "license": "MIT",
   "description": "Code PushUp plugin for detecting accessibility issues using Axe 🌐",
   "homepage": "https://github.com/code-pushup/cli/tree/main/packages/plugin-axe#readme",
@@ -42,8 +42,8 @@
   "type": "module",
   "dependencies": {
     "@axe-core/playwright": "^4.11.0",
-    "@code-pushup/models": "0.95.2",
-    "@code-pushup/utils": "0.95.2",
+    "@code-pushup/models": "0.96.0",
+    "@code-pushup/utils": "0.96.0",
     "axe-core": "^4.11.0",
     "playwright-core": "^1.56.1",
     "zod": "^4.1.12"

package/src/index.d.ts

@@ -1,4 +1,6 @@
 import { axePlugin } from './lib/axe-plugin.js';
 export default axePlugin;
-export type { AxePluginOptions } from './lib/config.js';
-export type { AxePreset } from './lib/config.js';
+export type { AxePluginOptions, AxePreset } from './lib/config.js';
+export type { AxeGroupSlug } from './lib/groups.js';
+export { axeAuditRef, axeGroupRef } from './lib/utils.js';
+export { axeCategories } from './lib/categories.js';

package/src/index.js

@@ -1,3 +1,5 @@
 import { axePlugin } from './lib/axe-plugin.js';
 export default axePlugin;
+export { axeAuditRef, axeGroupRef } from './lib/utils.js';
+export { axeCategories } from './lib/categories.js';
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,eAAe,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,eAAe,SAAS,CAAC;AAKzB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/src/lib/categories.d.ts

@@ -0,0 +1,22 @@
+import type { CategoryConfig, Group, PluginConfig } from '@code-pushup/models';
+import { type PluginUrlContext } from '@code-pushup/utils';
+import { type AxeCategoryGroupSlug } from './groups.js';
+/**
+ * Creates categories for the Axe plugin.
+ *
+ * @public
+ * @param plugin - {@link PluginConfig} object with groups and context
+ * @param categories - {@link CategoryConfig} optional user-defined categories
+ * @returns {CategoryConfig[]} - expanded and aggregated categories
+ *
+ * @example
+ * const axe = await axePlugin(urls);
+ * const axeCoreConfig = {
+ *   plugins: [axe],
+ *   categories: axeCategories(axe),
+ * };
+ */
+export declare function axeCategories(plugin: Pick<PluginConfig, 'groups' | 'context'>, categories?: CategoryConfig[]): CategoryConfig[];
+export declare function createAggregatedCategory(groups: Group[], context: PluginUrlContext): CategoryConfig;
+export declare function expandAggregatedCategory(category: CategoryConfig, context: PluginUrlContext): CategoryConfig;
+export declare function extractGroupSlugs(groups: Group[]): AxeCategoryGroupSlug[];

package/src/lib/categories.js

@@ -0,0 +1,56 @@
+import { createCategoryRefs, expandCategoryRefs, removeIndex, shouldExpandForUrls, validateUrlContext, } from '@code-pushup/utils';
+import { AXE_PLUGIN_SLUG } from './constants.js';
+import { isAxeGroupSlug } from './groups.js';
+/**
+ * Creates categories for the Axe plugin.
+ *
+ * @public
+ * @param plugin - {@link PluginConfig} object with groups and context
+ * @param categories - {@link CategoryConfig} optional user-defined categories
+ * @returns {CategoryConfig[]} - expanded and aggregated categories
+ *
+ * @example
+ * const axe = await axePlugin(urls);
+ * const axeCoreConfig = {
+ *   plugins: [axe],
+ *   categories: axeCategories(axe),
+ * };
+ */
+export function axeCategories(plugin, categories) {
+    if (!plugin.groups || plugin.groups.length === 0) {
+        return categories ?? [];
+    }
+    validateUrlContext(plugin.context);
+    if (!categories) {
+        return createCategories(plugin.groups, plugin.context);
+    }
+    return expandCategories(categories, plugin.context);
+}
+function createCategories(groups, context) {
+    return [createAggregatedCategory(groups, context)];
+}
+function expandCategories(categories, context) {
+    if (!shouldExpandForUrls(context.urlCount)) {
+        return categories;
+    }
+    return categories.map(category => expandAggregatedCategory(category, context));
+}
+export function createAggregatedCategory(groups, context) {
+    const refs = extractGroupSlugs(groups).flatMap(slug => createCategoryRefs(slug, AXE_PLUGIN_SLUG, context));
+    return {
+        slug: 'axe-a11y',
+        title: 'Axe Accessibility',
+        refs,
+    };
+}
+export function expandAggregatedCategory(category, context) {
+    return {
+        ...category,
+        refs: category.refs.flatMap(ref => ref.plugin === AXE_PLUGIN_SLUG ? expandCategoryRefs(ref, context) : [ref]),
+    };
+}
+export function extractGroupSlugs(groups) {
+    const slugs = groups.map(({ slug }) => removeIndex(slug));
+    return [...new Set(slugs)].filter(isAxeGroupSlug);
+}
+//# sourceMappingURL=categories.js.map

package/src/lib/categories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.js","sourceRoot":"","sources":["../../../src/lib/categories.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAA6B,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAgD,EAChD,UAA6B;IAE7B,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjD,OAAO,UAAU,IAAI,EAAE,CAAC;IAC1B,CAAC;IACD,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,gBAAgB,CAAC,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,gBAAgB,CACvB,MAAe,EACf,OAAyB;IAEzB,OAAO,CAAC,wBAAwB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,gBAAgB,CACvB,UAA4B,EAC5B,OAAyB;IAEzB,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3C,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAC/B,wBAAwB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,MAAe,EACf,OAAyB;IAEzB,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CACpD,kBAAkB,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,CACnD,CAAC;IACF,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,mBAAmB;QAC1B,IAAI;KACL,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,QAAwB,EACxB,OAAyB;IAEzB,OAAO;QACL,GAAG,QAAQ;QACX,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAChC,GAAG,CAAC,MAAM,KAAK,eAAe,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAC1E;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;AACpD,CAAC"}

package/src/lib/groups.d.ts

@@ -30,6 +30,7 @@ export declare const axeCategoryGroupSlugSchema: z.ZodEnum<{
 }>;
 export type AxeCategoryGroupSlug = z.infer<typeof axeCategoryGroupSlugSchema>;
 export declare const CATEGORY_GROUPS: Record<AxeCategoryGroupSlug, string>;
+export declare function isAxeGroupSlug(slug: unknown): slug is AxeCategoryGroupSlug;
 export declare const axeGroupSlugSchema: z.ZodEnum<{
     aria: "aria";
     color: "color";

package/src/lib/groups.js

@@ -55,6 +55,9 @@ export const CATEGORY_GROUPS = {
     'text-alternatives': 'Text Alternatives',
     'time-and-media': 'Media',
 };
+export function isAxeGroupSlug(slug) {
+    return axeCategoryGroupSlugSchema.safeParse(slug).success;
+}
 /* Combined exports */
 export const axeGroupSlugSchema = axeCategoryGroupSlugSchema;
 //# sourceMappingURL=groups.js.map

package/src/lib/groups.js.map

@@ -1 +1 @@
-{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../../src/lib/groups.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,mCAAmC;AACnC,MAAM,WAAW,GAAG;IAClB,QAAQ;IACR,SAAS;IACT,SAAS;IACT,UAAU;IACV,UAAU;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,IAAI,CAAC,WAAW,CAAC;KACjB,IAAI,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;AAIjC,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe;KAC/C,OAAO,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;KACjC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;AAIpC,MAAM,gBAAgB,GAAwC;IAC5D,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,CAAC;IACtD,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC;CACnE,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,MAAqB;IACrD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,qCAAqC;AACrC,MAAM,qBAAqB,GAAG;IAC5B,MAAM;IACN,OAAO;IACP,OAAO;IACP,UAAU;IACV,UAAU;IACV,iBAAiB;IACjB,SAAS;IACT,WAAW;IACX,yBAAyB;IACzB,WAAW;IACX,QAAQ;IACR,mBAAmB;IACnB,gBAAgB;CACR,CAAC;AAEX,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC;KACxC,IAAI,CAAC,qBAAqB,CAAC;KAC3B,IAAI,CAAC,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC,CAAC;AAI3C,MAAM,CAAC,MAAM,eAAe,GAAyC;IACnE,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,kBAAkB;IACzB,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,iBAAiB,EAAE,gBAAgB;IACnC,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,yBAAyB,EAAE,aAAa;IACxC,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;IAChB,mBAAmB,EAAE,mBAAmB;IACxC,gBAAgB,EAAE,OAAO;CAC1B,CAAC;AAEF,sBAAsB;AACtB,MAAM,CAAC,MAAM,kBAAkB,GAAG,0BAA0B,CAAC"}
+{"version":3,"file":"groups.js","sourceRoot":"","sources":["../../../src/lib/groups.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,mCAAmC;AACnC,MAAM,WAAW,GAAG;IAClB,QAAQ;IACR,SAAS;IACT,SAAS;IACT,UAAU;IACV,UAAU;CACF,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,IAAI,CAAC,WAAW,CAAC;KACjB,IAAI,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;AAIjC,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe;KAC/C,OAAO,CAAC,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;KACjC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;AAIpC,MAAM,gBAAgB,GAAwC;IAC5D,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,CAAC;IACtD,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC;CACnE,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,MAAqB;IACrD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED,qCAAqC;AACrC,MAAM,qBAAqB,GAAG;IAC5B,MAAM;IACN,OAAO;IACP,OAAO;IACP,UAAU;IACV,UAAU;IACV,iBAAiB;IACjB,SAAS;IACT,WAAW;IACX,yBAAyB;IACzB,WAAW;IACX,QAAQ;IACR,mBAAmB;IACnB,gBAAgB;CACR,CAAC;AAEX,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC;KACxC,IAAI,CAAC,qBAAqB,CAAC;KAC3B,IAAI,CAAC,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC,CAAC;AAI3C,MAAM,CAAC,MAAM,eAAe,GAAyC;IACnE,IAAI,EAAE,MAAM;IACZ,KAAK,EAAE,kBAAkB;IACzB,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;IACpB,iBAAiB,EAAE,gBAAgB;IACnC,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,yBAAyB,EAAE,aAAa;IACxC,SAAS,EAAE,WAAW;IACtB,MAAM,EAAE,QAAQ;IAChB,mBAAmB,EAAE,mBAAmB;IACxC,gBAAgB,EAAE,OAAO;CAC1B,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,OAAO,0BAA0B,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;AAC5D,CAAC;AAED,sBAAsB;AACtB,MAAM,CAAC,MAAM,kBAAkB,GAAG,0BAA0B,CAAC"}

package/src/lib/utils.d.ts

@@ -0,0 +1,4 @@
+import type { CategoryRef } from '@code-pushup/models';
+import type { AxeGroupSlug } from './groups.js';
+export declare function axeGroupRef(groupSlug: AxeGroupSlug, weight?: number): CategoryRef;
+export declare function axeAuditRef(auditSlug: string, weight?: number): CategoryRef;

package/src/lib/utils.js

@@ -0,0 +1,18 @@
+import { AXE_PLUGIN_SLUG } from './constants.js';
+export function axeGroupRef(groupSlug, weight = 1) {
+    return {
+        plugin: AXE_PLUGIN_SLUG,
+        slug: groupSlug,
+        type: 'group',
+        weight,
+    };
+}
+export function axeAuditRef(auditSlug, weight = 1) {
+    return {
+        plugin: AXE_PLUGIN_SLUG,
+        slug: auditSlug,
+        type: 'audit',
+        weight,
+    };
+}
+//# sourceMappingURL=utils.js.map

package/src/lib/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/lib/utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,MAAM,UAAU,WAAW,CAAC,SAAuB,EAAE,MAAM,GAAG,CAAC;IAC7D,OAAO;QACL,MAAM,EAAE,eAAe;QACvB,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,OAAO;QACb,MAAM;KACP,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,MAAM,GAAG,CAAC;IACvD,OAAO;QACL,MAAM,EAAE,eAAe;QACvB,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,OAAO;QACb,MAAM;KACP,CAAC;AACJ,CAAC"}