refactor(models,utils): extract shared URL utilities for plugins

Author: hanna-skryl

code-pushup.preset.ts

@@ -2,6 +2,7 @@
 import type {
   CategoryConfig,
   CoreConfig,
+  PluginUrls,
 } from './packages/models/src/index.js';
 import coveragePlugin, {
   getNxCoveragePaths,
@@ -20,7 +21,6 @@ import {
 } from './packages/plugin-jsdocs/src/lib/constants.js';
 import { filterGroupsByOnlyAudits } from './packages/plugin-jsdocs/src/lib/utils.js';
 import lighthousePlugin, {
-  type LighthouseUrls,
   lighthouseGroupRef,
   mergeLighthouseCategories,
 } from './packages/plugin-lighthouse/src/index.js';
@@ -137,7 +137,7 @@ export const jsPackagesCoreConfig = async (): Promise<CoreConfig> => ({
 });
 
 export const lighthouseCoreConfig = async (
-  urls: LighthouseUrls,
+  urls: PluginUrls,
 ): Promise<CoreConfig> => {
   const lhPlugin = await lighthousePlugin(urls);
   return {

packages/models/docs/models-reference.md

@@ -1366,6 +1366,16 @@ _Union of the following possible types:_
 - _Object with dynamic keys of type_ `string` _and values of type_ `number` (_≥0, ≤1_)
   (_optional_)
 
+## PluginUrls
+
+URL(s) to analyze. Single URL, array of URLs, or record of URLs with custom weights
+
+_Union of the following possible types:_
+
+- `string` (_url_)
+- `Array<string (_url_)>`
+- _Object with dynamic keys of type_ `string` (_url_) _and values of type_ `number` (_>0_)
+
 ## Report
 
 Collect output data

packages/models/src/index.ts

@@ -93,10 +93,12 @@ export {
   pluginContextSchema,
   pluginMetaSchema,
   pluginScoreTargetsSchema,
+  pluginUrlsSchema,
   type PluginConfig,
   type PluginContext,
   type PluginMeta,
   type PluginScoreTargets,
+  type PluginUrls,
 } from './lib/plugin-config.js';
 export {
   auditReportSchema,

packages/models/src/lib/plugin-config.ts

@@ -72,6 +72,16 @@ export const pluginConfigSchema = pluginMetaSchema
 
 export type PluginConfig = z.infer<typeof pluginConfigSchema>;
 
+export const pluginUrlsSchema = z
+  .union([z.url(), z.array(z.url()), z.record(z.url(), z.number().positive())])
+  .meta({
+    title: 'PluginUrls',
+    description:
+      'URL(s) to analyze. Single URL, array of URLs, or record of URLs with custom weights',
+  });
+
+export type PluginUrls = z.infer<typeof pluginUrlsSchema>;
+
 // every listed group ref points to an audit within the plugin
 export function findMissingSlugsInGroupRefs<
   T extends { audits: Audit[]; groups?: Group[] },

packages/models/src/lib/plugin-config.unit.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest';
-import { type PluginConfig, pluginConfigSchema } from './plugin-config.js';
+import {
+  type PluginConfig,
+  pluginConfigSchema,
+  pluginUrlsSchema,
+} from './plugin-config.js';
 
 describe('pluginConfigSchema', () => {
   it('should accept a valid plugin configuration with all entities', () => {
@@ -135,3 +139,37 @@ describe('pluginConfigSchema', () => {
     ).toThrow('slug has to follow the pattern');
   });
 });
+
+describe('pluginUrlsSchema', () => {
+  it('should accept a single URL string', () => {
+    expect(() => pluginUrlsSchema.parse('https://example.com')).not.toThrow();
+  });
+
+  it('should accept an array of URLs', () => {
+    expect(() =>
+      pluginUrlsSchema.parse([
+        'https://example.com',
+        'https://example.com/about',
+      ]),
+    ).not.toThrow();
+  });
+
+  it('should accept a weighted object of URLs', () => {
+    expect(() =>
+      pluginUrlsSchema.parse({
+        'https://example.com': 2,
+        'https://example.com/about': 1,
+      }),
+    ).not.toThrow();
+  });
+
+  it('should throw for invalid URL', () => {
+    expect(() => pluginUrlsSchema.parse('not-a-url')).toThrow();
+  });
+
+  it('should throw for array with invalid URL', () => {
+    expect(() =>
+      pluginUrlsSchema.parse(['https://example.com', 'invalid']),
+    ).toThrow();
+  });
+});

packages/plugin-lighthouse/src/index.ts

@@ -7,11 +7,7 @@ export {
   LIGHTHOUSE_OUTPUT_PATH,
 } from './lib/constants.js';
 export { lighthouseAuditRef, lighthouseGroupRef } from './lib/utils.js';
-export type {
-  LighthouseGroupSlug,
-  LighthouseOptions,
-  LighthouseUrls,
-} from './lib/types.js';
+export type { LighthouseGroupSlug, LighthouseOptions } from './lib/types.js';
 export { lighthousePlugin } from './lib/lighthouse-plugin.js';
 export default lighthousePlugin;
 export { mergeLighthouseCategories } from './lib/merge-categories.js';

packages/plugin-lighthouse/src/lib/lighthouse-plugin.ts

@@ -1,13 +1,14 @@
 import { createRequire } from 'node:module';
-import type { PluginConfig } from '@code-pushup/models';
+import type { PluginConfig, PluginUrls } from '@code-pushup/models';
+import { normalizeUrlInput } from '@code-pushup/utils';
 import { LIGHTHOUSE_PLUGIN_SLUG } from './constants.js';
 import { normalizeFlags } from './normalize-flags.js';
-import { normalizeUrlInput, processAuditsAndGroups } from './processing.js';
+import { processAuditsAndGroups } from './processing.js';
 import { createRunnerFunction } from './runner/runner.js';
-import type { LighthouseOptions, LighthouseUrls } from './types.js';
+import type { LighthouseOptions } from './types.js';
 
 export function lighthousePlugin(
-  urls: LighthouseUrls,
+  urls: PluginUrls,
   flags?: LighthouseOptions,
 ): PluginConfig {
   const {

packages/plugin-lighthouse/src/lib/merge-categories.ts

@@ -1,8 +1,15 @@
 import type { CategoryConfig, Group, PluginConfig } from '@code-pushup/models';
+import {
+  type PluginUrlContext,
+  createCategoryRefs,
+  expandCategoryRefs,
+  removeIndex,
+  shouldExpandForUrls,
+  validateUrlContext,
+} from '@code-pushup/utils';
 import { LIGHTHOUSE_GROUP_SLUGS, LIGHTHOUSE_PLUGIN_SLUG } from './constants.js';
-import { orderSlug, shouldExpandForUrls } from './processing.js';
 import { LIGHTHOUSE_GROUPS } from './runner/constants.js';
-import type { LighthouseContext, LighthouseGroupSlug } from './types.js';
+import type { LighthouseGroupSlug } from './types.js';
 import { isLighthouseGroupSlug } from './utils.js';
 
 /**
@@ -31,7 +38,7 @@ export function mergeLighthouseCategories(
   if (!plugin.groups || plugin.groups.length === 0) {
     return categories ?? [];
   }
-  validateContext(plugin.context);
+  validateUrlContext(plugin.context);
   if (!categories) {
     return createCategories(plugin.groups, plugin.context);
   }
@@ -40,7 +47,7 @@ export function mergeLighthouseCategories(
 
 function createCategories(
   groups: Group[],
-  context: LighthouseContext,
+  context: PluginUrlContext,
 ): CategoryConfig[] {
   if (!shouldExpandForUrls(context.urlCount)) {
     return [];
@@ -52,7 +59,7 @@ function createCategories(
 
 function expandCategories(
   categories: CategoryConfig[],
-  context: LighthouseContext,
+  context: PluginUrlContext,
 ): CategoryConfig[] {
   if (!shouldExpandForUrls(context.urlCount)) {
     return categories;
@@ -68,7 +75,7 @@ function expandCategories(
  */
 export function createAggregatedCategory(
   groupSlug: LighthouseGroupSlug,
-  context: LighthouseContext,
+  context: PluginUrlContext,
 ): CategoryConfig {
   const group = LIGHTHOUSE_GROUPS.find(({ slug }) => slug === groupSlug);
   if (!group) {
@@ -81,14 +88,7 @@ export function createAggregatedCategory(
     slug: group.slug,
     title: group.title,
     ...(group.description && { description: group.description }),
-    refs: Array.from({ length: context.urlCount }, (_, i) => ({
-      plugin: LIGHTHOUSE_PLUGIN_SLUG,
-      slug: shouldExpandForUrls(context.urlCount)
-        ? orderSlug(group.slug, i)
-        : group.slug,
-      type: 'group',
-      weight: resolveWeight(context.weights, i),
-    })),
+    refs: createCategoryRefs(group.slug, LIGHTHOUSE_PLUGIN_SLUG, context),
   };
 }
 
@@ -98,22 +98,15 @@ export function createAggregatedCategory(
  */
 export function expandAggregatedCategory(
   category: CategoryConfig,
-  context: LighthouseContext,
+  context: PluginUrlContext,
 ): CategoryConfig {
   return {
     ...category,
-    refs: category.refs.flatMap(ref => {
-      if (ref.plugin === LIGHTHOUSE_PLUGIN_SLUG) {
-        return Array.from({ length: context.urlCount }, (_, i) => ({
-          ...ref,
-          slug: shouldExpandForUrls(context.urlCount)
-            ? orderSlug(ref.slug, i)
-            : ref.slug,
-          weight: resolveWeight(context.weights, i, ref.weight),
-        }));
-      }
-      return [ref];
-    }),
+    refs: category.refs.flatMap(ref =>
+      ref.plugin === LIGHTHOUSE_PLUGIN_SLUG
+        ? expandCategoryRefs(ref, context)
+        : [ref],
+    ),
   };
 }
 
@@ -122,38 +115,6 @@ export function expandAggregatedCategory(
  * Useful for deduplicating and normalizing group slugs when generating categories.
  */
 export function extractGroupSlugs(groups: Group[]): LighthouseGroupSlug[] {
-  const slugs = groups.map(({ slug }) => slug.replace(/-\d+$/, ''));
+  const slugs = groups.map(({ slug }) => removeIndex(slug));
   return [...new Set(slugs)].filter(isLighthouseGroupSlug);
 }
-
-export class ContextValidationError extends Error {
-  constructor(message: string) {
-    super(`Invalid Lighthouse context: ${message}`);
-  }
-}
-
-export function validateContext(
-  context: PluginConfig['context'],
-): asserts context is LighthouseContext {
-  if (!context || typeof context !== 'object') {
-    throw new ContextValidationError('must be an object');
-  }
-  const { urlCount, weights } = context;
-  if (typeof urlCount !== 'number' || urlCount < 0) {
-    throw new ContextValidationError('urlCount must be a non-negative number');
-  }
-  if (!weights || typeof weights !== 'object') {
-    throw new ContextValidationError('weights must be an object');
-  }
-  if (Object.keys(weights).length !== urlCount) {
-    throw new ContextValidationError('weights count must match urlCount');
-  }
-}
-
-function resolveWeight(
-  weights: LighthouseContext['weights'],
-  index: number,
-  userDefinedWeight?: number,
-): number {
-  return weights[index + 1] ?? userDefinedWeight ?? 1;
-}

packages/plugin-lighthouse/src/lib/merge-categories.unit.test.ts

@@ -2,12 +2,10 @@ import { describe, expect, it } from 'vitest';
 import type { CategoryConfig } from '@code-pushup/models';
 import { LIGHTHOUSE_PLUGIN_SLUG } from './constants.js';
 import {
-  ContextValidationError,
   createAggregatedCategory,
   expandAggregatedCategory,
   extractGroupSlugs,
   mergeLighthouseCategories,
-  validateContext,
 } from './merge-categories.js';
 
 describe('mergeLighthouseCategories', () => {
@@ -830,35 +828,3 @@ describe('expandAggregatedCategory', () => {
     ]);
   });
 });
-
-describe('validateContext', () => {
-  it('should throw error for invalid context (undefined)', () => {
-    expect(() => validateContext(undefined)).toThrow(
-      new ContextValidationError('must be an object'),
-    );
-  });
-
-  it('should throw error for invalid context (missing urlCount)', () => {
-    expect(() => validateContext({ weights: {} })).toThrow(
-      new ContextValidationError('urlCount must be a non-negative number'),
-    );
-  });
-
-  it('should throw error for invalid context (negative urlCount)', () => {
-    expect(() => validateContext({ urlCount: -1, weights: {} })).toThrow(
-      new ContextValidationError('urlCount must be a non-negative number'),
-    );
-  });
-
-  it('should throw error for invalid context (missing weights)', () => {
-    expect(() => validateContext({ urlCount: 2 })).toThrow(
-      new ContextValidationError('weights must be an object'),
-    );
-  });
-
-  it('should accept valid context', () => {
-    expect(() =>
-      validateContext({ urlCount: 2, weights: { 1: 1, 2: 1 } }),
-    ).not.toThrow();
-  });
-});