docs(plugin-axe): improve documentation coverage

Author: hanna-skryl

packages/plugin-axe/src/lib/categories.ts

@@ -58,6 +58,7 @@ function expandCategories(
   );
 }
 
+/** Creates an aggregated accessibility category from Axe groups. */
 export function createAggregatedCategory(
   groups: Group[],
   context: PluginUrlContext,
@@ -72,6 +73,7 @@ export function createAggregatedCategory(
   };
 }
 
+/** Expands category refs for multiple URLs. */
 export function expandAggregatedCategory(
   category: CategoryConfig,
   context: PluginUrlContext,
@@ -84,6 +86,7 @@ export function expandAggregatedCategory(
   };
 }
 
+/** Extracts unique group slugs from Axe groups. */
 export function extractGroupSlugs(groups: Group[]): AxeCategoryGroupSlug[] {
   const slugs = groups.map(({ slug }) => removeIndex(slug));
   return [...new Set(slugs)].filter(isAxeGroupSlug);

packages/plugin-axe/src/lib/constants.ts

@@ -1,12 +1,18 @@
 import type { AxePreset } from './config.js';
 
+/** Unique identifier for the Axe plugin. */
 export const AXE_PLUGIN_SLUG = 'axe';
+
+/** Display title for the Axe plugin. */
 export const AXE_PLUGIN_TITLE = 'Axe';
 
+/** Default WCAG preset used when none is specified. */
 export const AXE_DEFAULT_PRESET = 'wcag21aa';
 
+/** Default timeout in milliseconds for page operations. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
 
+/** Human-readable names for each Axe preset. */
 export const AXE_PRESET_NAMES: Record<AxePreset, string> = {
   wcag21aa: 'WCAG 2.1 AA',
   wcag22aa: 'WCAG 2.2 AA',

packages/plugin-axe/src/lib/groups.ts

@@ -27,6 +27,7 @@ const WCAG_PRESET_TAGS: Record<AxeWcagPreset, AxeWcagTag[]> = {
   wcag22aa: ['wcag2a', 'wcag21a', 'wcag2aa', 'wcag21aa', 'wcag22aa'],
 };
 
+/** Returns the WCAG tags for a given preset. */
 export function getWcagPresetTags(preset: AxeWcagPreset): AxeWcagTag[] {
   return WCAG_PRESET_TAGS[preset];
 }
@@ -54,6 +55,7 @@ export const axeCategoryGroupSlugSchema = z
 
 export type AxeCategoryGroupSlug = z.infer<typeof axeCategoryGroupSlugSchema>;
 
+/** Maps category group slugs to human-readable titles. */
 export const CATEGORY_GROUPS: Record<AxeCategoryGroupSlug, string> = {
   aria: 'ARIA',
   color: 'Color & Contrast',
@@ -70,6 +72,7 @@ export const CATEGORY_GROUPS: Record<AxeCategoryGroupSlug, string> = {
   'time-and-media': 'Media',
 };
 
+/** Type guard for valid Axe group slugs. */
 export function isAxeGroupSlug(slug: unknown): slug is AxeCategoryGroupSlug {
   return axeCategoryGroupSlugSchema.safeParse(slug).success;
 }

packages/plugin-axe/src/lib/meta/format.ts

@@ -1,4 +1,5 @@
 import { pluginMetaLogFormatter } from '@code-pushup/utils';
 import { AXE_PLUGIN_TITLE } from '../constants.js';
 
+/** Formats log messages with the Axe plugin prefix. */
 export const formatMetaLog = pluginMetaLogFormatter(AXE_PLUGIN_TITLE);

packages/plugin-axe/src/lib/meta/processing.ts

@@ -16,6 +16,7 @@ import {
   transformRulesToGroups,
 } from './transform.js';
 
+/** Loads and processes Axe rules into audits and groups, expanding for multiple URLs if needed. */
 export function processAuditsAndGroups(
   urls: string[],
   preset: AxePreset,

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

@@ -8,11 +8,13 @@ import {
   getWcagPresetTags,
 } from '../groups.js';
 
+/** Loads Axe rules filtered by the specified preset. */
 export function loadAxeRules(preset: AxePreset): axe.RuleMetadata[] {
   const tags = getPresetTags(preset);
   return tags.length === 0 ? axe.getRules() : axe.getRules(tags);
 }
 
+/** Transforms Axe rule metadata into Code PushUp audit definitions. */
 export function transformRulesToAudits(rules: axe.RuleMetadata[]): Audit[] {
   return rules.map(rule => ({
     slug: rule.ruleId,
@@ -22,6 +24,7 @@ export function transformRulesToAudits(rules: axe.RuleMetadata[]): Audit[] {
   }));
 }
 
+/** Transforms Axe rules into Code PushUp groups based on accessibility categories. */
 export function transformRulesToGroups(rules: axe.RuleMetadata[]): Group[] {
   const groups = createCategoryGroups(rules);
   return groups.filter(({ refs }) => refs.length > 0);

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

@@ -34,11 +34,16 @@ export type AxeUrlResult = {
   auditOutputs: AuditOutputs;
 };
 
+/**
+ * Manages Playwright browser lifecycle and runs Axe accessibility audits.
+ * Handles browser installation, authentication state, and URL analysis.
+ */
 export class AxeRunner {
   private browser: Browser | undefined;
   private browserInstalled = false;
   private storageState: BrowserContextOptions['storageState'];
 
+  /** Analyzes a URL for accessibility issues using Axe. */
   async analyzeUrl(args: AxeUrlArgs): Promise<AxeUrlResult> {
     const browser = await this.launchBrowser();
     const { url, urlIndex, urlsCount } = args;
@@ -67,6 +72,7 @@ export class AxeRunner {
     });
   }
 
+  /** Runs setup script and captures authentication state for reuse. */
   async captureAuthState(
     setupFn: SetupFunction,
     timeout: number,
@@ -87,6 +93,7 @@ export class AxeRunner {
     }
   }
 
+  /** Closes the browser and clears authentication state. */
   async close(): Promise<void> {
     this.storageState = undefined;
     this.browserInstalled = false;
@@ -127,6 +134,7 @@ export class AxeRunner {
     this.browserInstalled = true;
   }
 
+  /** Lazily launches or returns existing Chromium browser instance. */
   private async launchBrowser(): Promise<Browser> {
     if (this.browser) {
       return this.browser;

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

@@ -11,6 +11,7 @@ import {
 import { AxeRunner, type AxeUrlArgs, type AxeUrlResult } from './run-axe.js';
 import { loadSetupScript } from './setup.js';
 
+/** Creates a runner function that executes Axe accessibility audits for given URLs. */
 export function createRunnerFunction(
   urls: string[],
   ruleIds: string[],

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

@@ -26,6 +26,7 @@ const setupScriptModuleSchema = z
       'ES module with a default export containing the authentication setup function',
   });
 
+/** Loads and validates a setup script module from the given path. */
 export async function loadSetupScript(
   setupScript: string,
 ): Promise<SetupFunction> {
@@ -47,6 +48,7 @@ export async function loadSetupScript(
   return validModule.default;
 }
 
+/** Executes the setup function with the provided Playwright page. */
 export async function runSetup(
   setupFn: SetupFunction,
   page: Page,

packages/plugin-axe/src/lib/utils.ts

@@ -2,6 +2,7 @@ import type { CategoryRef } from '@code-pushup/models';
 import { AXE_PLUGIN_SLUG } from './constants.js';
 import type { AxeGroupSlug } from './groups.js';
 
+/** Creates a category ref to an Axe group. */
 export function axeGroupRef(groupSlug: AxeGroupSlug, weight = 1): CategoryRef {
   return {
     plugin: AXE_PLUGIN_SLUG,
@@ -11,6 +12,7 @@ export function axeGroupRef(groupSlug: AxeGroupSlug, weight = 1): CategoryRef {
   };
 }
 
+/** Creates a category ref to an Axe audit. */
 export function axeAuditRef(auditSlug: string, weight = 1): CategoryRef {
   return {
     plugin: AXE_PLUGIN_SLUG,