feat: add transform to persist config (#229)

packages/core/src/index.ts

@@ -5,7 +5,7 @@ export {
 } from './lib/implementation/persist';
 export {
   executePlugins,
-  PluginOutputError,
+  PluginOutputMissingAuditError,
 } from './lib/implementation/execute-plugin';
 export { collect, CollectOptions } from './lib/implementation/collect';
 export { upload, UploadOptions } from './lib/upload';

packages/core/src/lib/implementation/execute-plugin.spec.ts

@@ -1,17 +1,17 @@
-import { join } from 'path';
 import { describe, expect, it } from 'vitest';
 import {
-  AuditReport,
+  AuditOutput,
+  AuditOutputs,
   PluginConfig,
   auditOutputsSchema,
 } from '@code-pushup/models';
-import {
-  auditReport,
-  echoRunnerConfig,
-  pluginConfig,
-} from '@code-pushup/models/testing';
+import { auditReport, pluginConfig } from '@code-pushup/models/testing';
 import { DEFAULT_TESTING_CLI_OPTIONS } from '../../../test/constants';
-import { executePlugin, executePlugins } from './execute-plugin';
+import {
+  PluginOutputMissingAuditError,
+  executePlugin,
+  executePlugins,
+} from './execute-plugin';
 
 const validPluginCfg = pluginConfig([auditReport()]);
 const validPluginCfg2 = pluginConfig([auditReport()], {
@@ -35,24 +35,28 @@ describe('executePlugin', () => {
     expect(() => auditOutputsSchema.parse(pluginResult.audits)).not.toThrow();
   });
 
-  it('should throws with invalid plugin audits slug', async () => {
+  it('should throw with missing plugin audit', async () => {
     const pluginCfg = invalidSlugPluginCfg;
     await expect(() => executePlugin(pluginCfg)).rejects.toThrow(
-      /Plugin output of plugin .* is invalid./,
+      new PluginOutputMissingAuditError('mock-audit-slug'),
     );
   });
 
-  it('should throw if invalid runnerOutput is produced', async () => {
-    const invalidAuditOutputs: AuditReport[] = [
-      { p: 42 } as unknown as AuditReport,
-    ];
-    const pluginCfg = pluginConfig([auditReport()]);
-    pluginCfg.runner = echoRunnerConfig(
-      invalidAuditOutputs,
-      join('tmp', 'out.json'),
-    );
+  it('should throw if invalid runnerOutput is produced with transform', async () => {
+    const pluginCfg: PluginConfig = {
+      ...validPluginCfg,
+      runner: {
+        ...validPluginCfg.runner,
+        outputTransform: (d: unknown) =>
+          Array.from(d as Record<string, unknown>[]).map((d, idx) => ({
+            ...d,
+            slug: '-invalid-slug-' + idx,
+          })) as unknown as AuditOutputs,
+      },
+    };
+
     await expect(() => executePlugin(pluginCfg)).rejects.toThrow(
-      /Plugin output of plugin .* is invalid./,
+      'The slug has to follow the pattern',
     );
   });
 });
@@ -79,6 +83,34 @@ describe('executePlugins', () => {
     const plugins: PluginConfig[] = [validPluginCfg, invalidSlugPluginCfg];
     await expect(() =>
       executePlugins(plugins, DEFAULT_OPTIONS),
-    ).rejects.toThrow(/Plugin output of plugin .* is invalid./);
+    ).rejects.toThrow('Audit metadata not found for slug mock-audit-slug');
+  });
+
+  it('should use outputTransform if provided', async () => {
+    const plugins: PluginConfig[] = [
+      {
+        ...validPluginCfg,
+        runner: {
+          ...validPluginCfg.runner,
+          outputTransform: (outputs: unknown): Promise<AuditOutputs> => {
+            const arr = Array.from(outputs as Record<string, unknown>[]);
+            return Promise.resolve(
+              arr.map(output => {
+                return {
+                  ...output,
+                  displayValue:
+                    'transformed slug description - ' +
+                    (output as { slug: string }).slug,
+                } as unknown as AuditOutput;
+              }),
+            );
+          },
+        },
+      },
+    ];
+    const pluginResult = await executePlugins(plugins, DEFAULT_OPTIONS);
+    expect(pluginResult[0]?.audits[0]?.displayValue).toBe(
+      'transformed slug description - mock-audit-slug',
+    );
   });
 });

packages/core/src/lib/implementation/execute-plugin.ts

@@ -1,7 +1,10 @@
 import chalk from 'chalk';
-import { readFile } from 'fs/promises';
 import { join } from 'path';
 import {
+  Audit,
+  AuditOutput,
+  AuditOutputs,
+  AuditReport,
   PluginConfig,
   PluginReport,
   auditOutputsSchema,
@@ -10,20 +13,15 @@ import {
   ProcessObserver,
   executeProcess,
   getProgressBar,
+  readJsonFile,
 } from '@code-pushup/utils';
 
 /**
  * Error thrown when plugin output is invalid.
  */
-export class PluginOutputError extends Error {
-  constructor(pluginSlug: string, error?: Error) {
-    super(
-      `Plugin output of plugin with slug ${pluginSlug} is invalid. \n Error: ${error?.message}`,
-    );
-    if (error) {
-      this.name = error.name;
-      this.stack = error.stack;
-    }
+export class PluginOutputMissingAuditError extends Error {
+  constructor(auditSlug: string) {
+    super(`Audit metadata not found for slug ${auditSlug}`);
   }
 }
 
@@ -34,7 +32,7 @@ export class PluginOutputError extends Error {
  * @param pluginConfig - {@link ProcessConfig} object with runner and meta
  * @param observer - process {@link ProcessObserver}
  * @returns {Promise<AuditOutput[]>} - audit outputs from plugin runner
- * @throws {PluginOutputError} - if plugin runner output is invalid
+ * @throws {PluginOutputMissingAuditError} - if plugin runner output is invalid
  *
  * @example
  * // plugin execution
@@ -54,70 +52,61 @@ export async function executePlugin(
   observer?: ProcessObserver,
 ): Promise<PluginReport> {
   const {
-    slug,
-    title,
-    icon,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    runner: onlyUsedForRestingPluginMeta,
+    audits: pluginConfigAudits,
     description,
     docsUrl,
-    version,
-    packageName,
     groups,
+    ...pluginMeta
   } = pluginConfig;
   const { args, command } = pluginConfig.runner;
 
-  const { duration, date } = await executeProcess({
+  const { date, duration } = await executeProcess({
     command,
     args,
     observer,
   });
+  const executionMeta = { date, duration };
 
-  try {
-    const processOutputPath = join(
-      process.cwd(),
-      pluginConfig.runner.outputFile,
-    );
+  const processOutputPath = join(process.cwd(), pluginConfig.runner.outputFile);
+
+  // read process output from file system and parse it
+  let unknownAuditOutputs = await readJsonFile<Record<string, unknown>[]>(
+    processOutputPath,
+  );
 
-    // read process output from file system and parse it
-    const auditOutputs = auditOutputsSchema.parse(
-      JSON.parse((await readFile(processOutputPath)).toString()),
+  // parse transform unknownAuditOutputs to auditOutputs
+  if (pluginConfig.runner?.outputTransform) {
+    unknownAuditOutputs = await pluginConfig.runner.outputTransform(
+      unknownAuditOutputs,
     );
+  }
+
+  // validate audit outputs
+  const auditOutputs = auditOutputsSchema.parse(unknownAuditOutputs);
+
+  // validate auditOutputs
+  auditOutputsCorrelateWithPluginOutput(auditOutputs, pluginConfigAudits);
 
-    const audits = auditOutputs.map(auditOutput => {
-      const auditMetadata = pluginConfig.audits.find(
+  // enrich `AuditOutputs` to `AuditReport`
+  const audits: AuditReport[] = auditOutputs.map(
+    (auditOutput: AuditOutput) => ({
+      ...auditOutput,
+      ...(pluginConfigAudits.find(
         audit => audit.slug === auditOutput.slug,
-      );
-      if (!auditMetadata) {
-        throw new PluginOutputError(
-          slug,
-          new Error(
-            `Audit metadata not found for slug ${auditOutput.slug} from runner output`,
-          ),
-        );
-      }
-      return {
-        ...auditOutput,
-        ...auditMetadata,
-      };
-    });
-
-    // @TODO consider just resting/spreading the values
-    return {
-      version,
-      packageName,
-      slug,
-      title,
-      icon,
-      date,
-      duration,
-      audits,
-      ...(description && { description }),
-      ...(docsUrl && { docsUrl }),
-      ...(groups && { groups }),
-    } satisfies PluginReport;
-  } catch (error) {
-    const e = error as Error;
-    throw new PluginOutputError(slug, e);
-  }
+      ) as Audit),
+    }),
+  );
+
+  return {
+    ...pluginMeta,
+    ...executionMeta,
+    audits,
+    ...(description && { description }),
+    ...(docsUrl && { docsUrl }),
+    ...(groups && { groups }),
+  } satisfies PluginReport;
 }
 
 /**
@@ -165,3 +154,17 @@ export async function executePlugins(
 
   return pluginsResult;
 }
+
+function auditOutputsCorrelateWithPluginOutput(
+  auditOutputs: AuditOutputs,
+  pluginConfigAudits: PluginConfig['audits'],
+) {
+  auditOutputs.forEach(auditOutput => {
+    const auditMetadata = pluginConfigAudits.find(
+      audit => audit.slug === auditOutput.slug,
+    );
+    if (!auditMetadata) {
+      throw new PluginOutputMissingAuditError(auditOutput.slug);
+    }
+  });
+}

packages/models/src/index.ts

@@ -29,10 +29,15 @@ export {
   AuditGroup,
   auditGroupSchema,
 } from './lib/plugin-config-groups';
-export { AuditOutput, auditOutputsSchema } from './lib/plugin-process-output';
+export {
+  AuditOutput,
+  AuditOutputs,
+  auditOutputsSchema,
+} from './lib/plugin-process-output';
 export { Issue, IssueSeverity } from './lib/plugin-process-output-audit-issue';
 export {
   AuditReport,
+  auditReportSchema,
   PluginReport,
   Report,
   pluginReportSchema,

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

@@ -1,5 +1,13 @@
 import { z } from 'zod';
 import { filePathSchema } from './implementation/schemas';
+import { auditOutputsSchema } from './plugin-process-output';
+
+export const outputTransformSchema = z
+  .function()
+  .args(z.unknown())
+  .returns(z.union([auditOutputsSchema, z.promise(auditOutputsSchema)]));
+
+export type OutputTransform = z.infer<typeof outputTransformSchema>;
 
 export const runnerConfigSchema = z.object(
   {
@@ -8,6 +16,7 @@ export const runnerConfigSchema = z.object(
     }),
     args: z.array(z.string({ description: 'Command arguments' })).optional(),
     outputFile: filePathSchema('Output path'),
+    outputTransform: outputTransformSchema.optional(),
   },
   {
     description: 'How to execute runner',

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

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
-import { config } from '../../test';
+import { config, pluginConfig } from '../../test';
 import { pluginConfigSchema } from './plugin-config';
+import { AuditOutputs } from './plugin-process-output';
 
 describe('pluginConfigSchema', () => {
   it('should parse if plugin configuration is valid', () => {
@@ -40,7 +41,7 @@ describe('pluginConfigSchema', () => {
   it('should throw if plugin groups contain invalid slugs', () => {
     const invalidGroupSlug = '-invalid-group-slug';
     const pluginConfig = config().plugins[1];
-    const groups = pluginConfig.groups;
+    const groups = pluginConfig.groups!;
     groups[0].slug = invalidGroupSlug;
     pluginConfig.groups = groups;
 
@@ -51,7 +52,7 @@ describe('pluginConfigSchema', () => {
 
   it('should throw if plugin groups have duplicate slugs', () => {
     const pluginConfig = config().plugins[1];
-    const groups = pluginConfig.groups;
+    const groups = pluginConfig.groups!;
     pluginConfig.groups = [...groups, groups[0]];
     expect(() => pluginConfigSchema.parse(pluginConfig)).toThrow(
       'In groups the slugs are not unique',
@@ -61,7 +62,7 @@ describe('pluginConfigSchema', () => {
   it('should throw if plugin groups refs contain invalid slugs', () => {
     const invalidAuditRef = '-invalid-audit-ref';
     const pluginConfig = config().plugins[1];
-    const groups = pluginConfig.groups;
+    const groups = pluginConfig.groups!;
 
     groups[0].refs[0].slug = invalidAuditRef;
     pluginConfig.groups = groups;
@@ -70,4 +71,31 @@ describe('pluginConfigSchema', () => {
       `slug has to follow the pattern`,
     );
   });
+
+  it('should take a outputTransform function', () => {
+    const undefinedPluginOutput = [
+      { slug: 'audit-1', errors: 0 },
+      { slug: 'audit-2', errors: 5 },
+    ];
+    const pluginCfg = pluginConfig([]);
+    pluginCfg.runner.outputTransform = (data: unknown): AuditOutputs => {
+      return (data as typeof undefinedPluginOutput).map(data => ({
+        slug: data.slug,
+        score: Number(data.errors === 0),
+        value: data.errors,
+      }));
+    };
+
+    expect(
+      pluginConfigSchema.parse(pluginCfg).runner.outputTransform,
+    ).toBeDefined();
+    expect(
+      pluginConfigSchema.parse(pluginCfg).runner.outputTransform!(
+        undefinedPluginOutput,
+      ),
+    ).toEqual([
+      { slug: 'audit-1', score: 1, value: 0 },
+      { slug: 'audit-2', score: 0, value: 5 },
+    ]);
+  });
 });