feat(models,core): make runner args extensible by nesting persist config

Author: matejchalk

packages/core/src/lib/implementation/collect.ts

@@ -1,17 +1,16 @@
 import { createRequire } from 'node:module';
-import {
-  type CacheConfigObject,
-  type CoreConfig,
-  DEFAULT_PERSIST_OUTPUT_DIR,
-  type PersistConfig,
-  type Report,
+import type {
+  CacheConfigObject,
+  CoreConfig,
+  PersistConfig,
+  Report,
 } from '@code-pushup/models';
 import { calcDuration, getLatestCommit } from '@code-pushup/utils';
 import type { GlobalOptions } from '../types.js';
 import { executePlugins } from './execute-plugin.js';
 
 export type CollectOptions = Pick<CoreConfig, 'plugins' | 'categories'> & {
-  persist?: Required<Pick<PersistConfig, 'outputDir'>>;
+  persist?: PersistConfig;
   cache: CacheConfigObject;
 } & Partial<GlobalOptions>;
 
@@ -20,16 +19,12 @@ export type CollectOptions = Pick<CoreConfig, 'plugins' | 'categories'> & {
  * @param options
  */
 export async function collect(options: CollectOptions): Promise<Report> {
-  const { plugins, categories, persist, cache, ...otherOptions } = options;
+  const { plugins, categories, persist = {}, cache, ...otherOptions } = options;
   const date = new Date().toISOString();
   const start = performance.now();
   const commit = await getLatestCommit();
   const pluginOutputs = await executePlugins(
-    {
-      plugins,
-      persist: { outputDir: DEFAULT_PERSIST_OUTPUT_DIR, ...persist },
-      cache,
-    },
+    { plugins, persist, cache },
     otherOptions,
   );
   const packageJson = createRequire(import.meta.url)(

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

@@ -1,12 +1,13 @@
 import { bold } from 'ansis';
-import type {
-  Audit,
-  AuditOutput,
-  AuditReport,
-  CacheConfigObject,
-  PersistConfig,
-  PluginConfig,
-  PluginReport,
+import {
+  type AuditOutput,
+  type AuditReport,
+  type CacheConfigObject,
+  DEFAULT_PERSIST_CONFIG,
+  type PersistConfig,
+  type PluginConfig,
+  type PluginReport,
+  type RunnerArgs,
 } from '@code-pushup/models';
 import {
   type ProgressBar,
@@ -48,10 +49,9 @@ export async function executePlugin(
   pluginConfig: PluginConfig,
   opt: {
     cache: CacheConfigObject;
-    persist: Required<Pick<PersistConfig, 'outputDir'>>;
+    persist: PersistConfig;
   },
 ): Promise<PluginReport> {
-  const { cache, persist } = opt;
   const {
     runner,
     audits: pluginConfigAudits,
@@ -61,15 +61,19 @@ export async function executePlugin(
     scoreTargets,
     ...pluginMeta
   } = pluginConfig;
-  const { write: cacheWrite = false, read: cacheRead = false } = cache;
-  const { outputDir } = persist;
+  const { write: cacheWrite = false, read: cacheRead = false } = opt.cache;
+
+  const args: RunnerArgs = {
+    persist: { ...DEFAULT_PERSIST_CONFIG, ...opt.persist },
+  };
+  const { outputDir } = args.persist;
 
   const { audits, ...executionMeta } = cacheRead
     ? // IF not null, take the result from cache
       ((await readRunnerResults(pluginMeta.slug, outputDir)) ??
       // ELSE execute the plugin runner
-      (await executePluginRunner(pluginConfig, persist)))
-    : await executePluginRunner(pluginConfig, persist);
+      (await executePluginRunner(pluginConfig, args)))
+    : await executePluginRunner(pluginConfig, args);
 
   if (cacheWrite) {
     await writeRunnerResults(pluginMeta.slug, outputDir, {
@@ -87,9 +91,8 @@ export async function executePlugin(
   const auditReports: AuditReport[] = scoredAuditsWithTarget.map(
     (auditOutput: AuditOutput) => ({
       ...auditOutput,
-      ...(pluginConfigAudits.find(
-        audit => audit.slug === auditOutput.slug,
-      ) as Audit),
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      ...pluginConfigAudits.find(audit => audit.slug === auditOutput.slug)!,
     }),
   );
 
@@ -107,7 +110,7 @@ export async function executePlugin(
 const wrapProgress = async (
   cfg: {
     plugin: PluginConfig;
-    persist: Required<Pick<PersistConfig, 'outputDir'>>;
+    persist: PersistConfig;
     cache: CacheConfigObject;
   },
   steps: number,
@@ -155,7 +158,7 @@ const wrapProgress = async (
 export async function executePlugins(
   cfg: {
     plugins: PluginConfig[];
-    persist: Required<Pick<PersistConfig, 'outputDir'>>;
+    persist: PersistConfig;
     cache: CacheConfigObject;
   },
   options?: { progress?: boolean },

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

@@ -1,7 +1,11 @@
 import { bold } from 'ansis';
 import { vol } from 'memfs';
 import { describe, expect, it, vi } from 'vitest';
-import type { AuditOutputs, PluginConfig } from '@code-pushup/models';
+import {
+  type AuditOutputs,
+  DEFAULT_PERSIST_CONFIG,
+  type PluginConfig,
+} from '@code-pushup/models';
 import {
   MEMFS_VOLUME,
   MINIMAL_PLUGIN_CONFIG_MOCK,
@@ -26,7 +30,7 @@ describe('executePlugin', () => {
 
     await expect(
       executePlugin(MINIMAL_PLUGIN_CONFIG_MOCK, {
-        persist: { outputDir: '' },
+        persist: {},
         cache: { read: false, write: false },
       }),
     ).resolves.toStrictEqual({
@@ -47,7 +51,7 @@ describe('executePlugin', () => {
 
     expect(executePluginRunnerSpy).toHaveBeenCalledWith(
       MINIMAL_PLUGIN_CONFIG_MOCK,
-      { outputDir: '' },
+      { persist: DEFAULT_PERSIST_CONFIG },
     );
   });
 
@@ -132,7 +136,7 @@ describe('executePlugin', () => {
 
     expect(executePluginRunnerSpy).toHaveBeenCalledWith(
       MINIMAL_PLUGIN_CONFIG_MOCK,
-      { outputDir: MEMFS_VOLUME },
+      { persist: { ...DEFAULT_PERSIST_CONFIG, outputDir: MEMFS_VOLUME } },
     );
   });
 

packages/core/src/lib/implementation/runner.ts

@@ -3,8 +3,8 @@ import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import {
   type AuditOutputs,
-  type PersistConfig,
   type PluginConfig,
+  type RunnerArgs,
   type RunnerConfig,
   type RunnerFunction,
   auditOutputsSchema,
@@ -33,14 +33,14 @@ export type ValidatedRunnerResult = Omit<RunnerResult, 'audits'> & {
 };
 
 export async function executeRunnerConfig(
-  cfg: RunnerConfig,
-  config: Required<Pick<PersistConfig, 'outputDir'>>,
+  config: RunnerConfig,
+  args: RunnerArgs,
 ): Promise<RunnerResult> {
-  const { args, command, outputFile, outputTransform } = cfg;
+  const { outputFile, outputTransform } = config;
 
   const { duration, date } = await executeProcess({
-    command,
-    args: [...(args ?? []), ...objectToCliArgs(config)],
+    command: config.command,
+    args: [...(config.args ?? []), ...objectToCliArgs(args)],
     observer: {
       onStdout: stdout => {
         if (isVerbose()) {
@@ -69,13 +69,13 @@ export async function executeRunnerConfig(
 
 export async function executeRunnerFunction(
   runner: RunnerFunction,
-  config: PersistConfig,
+  args: RunnerArgs,
 ): Promise<RunnerResult> {
   const date = new Date().toISOString();
   const start = performance.now();
 
   // execute plugin runner
-  const audits = await runner(config);
+  const audits = await runner(args);
 
   // create runner result
   return {
@@ -100,13 +100,13 @@ export class AuditOutputsMissingAuditError extends Error {
 
 export async function executePluginRunner(
   pluginConfig: Pick<PluginConfig, 'audits' | 'runner'>,
-  persist: Required<Pick<PersistConfig, 'outputDir'>>,
+  args: RunnerArgs,
 ): Promise<Omit<RunnerResult, 'audits'> & { audits: AuditOutputs }> {
   const { audits: pluginConfigAudits, runner } = pluginConfig;
   const runnerResult: RunnerResult =
     typeof runner === 'object'
-      ? await executeRunnerConfig(runner, persist)
-      : await executeRunnerFunction(runner, persist);
+      ? await executeRunnerConfig(runner, args)
+      : await executeRunnerFunction(runner, args);
   const { audits: unvalidatedAuditOutputs, ...executionMeta } = runnerResult;
 
   const result = auditOutputsSchema.safeParse(unvalidatedAuditOutputs);

packages/models/docs/models-reference.md

@@ -1404,9 +1404,21 @@ _Object containing the following properties:_
 
 _(\*) Required._
 
+## RunnerArgs
+
+Arguments passed to runner
+
+_Object containing the following properties:_
+
+| Property           | Description                          | Type                                                                                                                                                                                                                                                                                             |
+| :----------------- | :----------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`persist`** (\*) | Persist config with defaults applied | _Object with properties:_<ul><li>**`outputDir`** (\*): `string` (_min length: 1_)</li><li>**`filename`** (\*): `string` (_regex: `/^(?!.*[ \\/:*?"<>\|]).+$/`, min length: 1_)</li><li>**`format`** (\*): _Array of [Format](#format) items_</li><li>**`skipReports`** (\*): `boolean`</li></ul> |
+
+_(\*) Required._
+
 ## RunnerConfig
 
-How to execute runner
+How to execute runner using shell script
 
 _Object containing the following properties:_
 
@@ -1433,11 +1445,13 @@ _(\*) Required._
 
 ## RunnerFunction
 
+Callback function for async runner execution in JS/TS
+
 _Function._
 
 _Parameters:_
 
-1. [PersistConfig](#persistconfig)
+1. [RunnerArgs](#runnerargs)
 
 _Returns:_
 

packages/models/src/index.ts

@@ -53,6 +53,7 @@ export {
   DEFAULT_PERSIST_FILENAME,
   DEFAULT_PERSIST_FORMAT,
   DEFAULT_PERSIST_OUTPUT_DIR,
+  DEFAULT_PERSIST_SKIP_REPORT,
 } from './lib/implementation/constants.js';
 export {
   MAX_DESCRIPTION_LENGTH,
@@ -117,9 +118,11 @@ export {
   type ReportsDiff,
 } from './lib/reports-diff.js';
 export {
+  runnerArgsSchema,
   runnerConfigSchema,
   runnerFilesPathsSchema,
   runnerFunctionSchema,
+  type RunnerArgs,
   type RunnerConfig,
   type RunnerFilesPaths,
   type RunnerFunction,

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

@@ -12,6 +12,15 @@ export const outputTransformSchema = convertAsyncZodFunctionToSchema(
 );
 export type OutputTransform = z.infer<typeof outputTransformSchema>;
 
+export const runnerArgsSchema = z
+  .object({
+    persist: persistConfigSchema
+      .required()
+      .describe('Persist config with defaults applied'),
+  })
+  .describe('Arguments passed to runner');
+export type RunnerArgs = z.infer<typeof runnerArgsSchema>;
+
 export const runnerConfigSchema = z
   .object({
     command: z.string().describe('Shell command to execute'),
@@ -20,22 +29,19 @@ export const runnerConfigSchema = z
     outputTransform: outputTransformSchema.optional(),
     configFile: filePathSchema.describe('Runner config path').optional(),
   })
-  .describe('How to execute runner');
-
+  .describe('How to execute runner using shell script');
 export type RunnerConfig = z.infer<typeof runnerConfigSchema>;
 
 export const runnerFunctionSchema = convertAsyncZodFunctionToSchema(
   z.function({
-    input: [persistConfigSchema],
+    input: [runnerArgsSchema],
     output: z.union([auditOutputsSchema, z.promise(auditOutputsSchema)]),
   }),
-);
-
+).describe('Callback function for async runner execution in JS/TS');
 export type RunnerFunction = z.infer<typeof runnerFunctionSchema>;
 
 export const runnerFilesPathsSchema = z.object({
   runnerConfigPath: filePathSchema.describe('Runner config path'),
   runnerOutputPath: filePathSchema.describe('Runner output path'),
 });
-
 export type RunnerFilesPaths = z.infer<typeof runnerFilesPathsSchema>;

packages/plugin-eslint/src/lib/runner.int.test.ts

@@ -7,7 +7,7 @@ import {
   type Audit,
   type AuditOutput,
   type AuditOutputs,
-  DEFAULT_PERSIST_OUTPUT_DIR,
+  DEFAULT_PERSIST_CONFIG,
   type Issue,
 } from '@code-pushup/models';
 import { osAgnosticAuditOutputs } from '@code-pushup/test-utils';
@@ -50,9 +50,9 @@ describe('executeRunner', () => {
 
   it('should execute ESLint and create audit results for React application', async () => {
     const args = await prepareRunnerArgs('eslint.config.js');
-    const runnerFn = await createRunnerFunction(args);
+    const runnerFn = createRunnerFunction(args);
     const res = (await runnerFn({
-      outputDir: DEFAULT_PERSIST_OUTPUT_DIR,
+      persist: DEFAULT_PERSIST_CONFIG,
     })) as AuditOutputs;
     expect(osAgnosticAuditOutputs(res)).toMatchSnapshot();
   });
@@ -61,11 +61,11 @@ describe('executeRunner', () => {
     'should execute runner with custom config using @code-pushup/eslint-config',
     async () => {
       const eslintTarget = 'code-pushup.eslint.config.mjs';
-      const runnerFn = await createRunnerFunction({
+      const runnerFn = createRunnerFunction({
         ...(await prepareRunnerArgs(eslintTarget)),
       });
 
-      const json = await runnerFn({ outputDir: DEFAULT_PERSIST_OUTPUT_DIR });
+      const json = await runnerFn({ persist: DEFAULT_PERSIST_CONFIG });
       // expect warnings from unicorn/filename-case rule from default config
       expect(json).toContainEqual(
         expect.objectContaining<Partial<AuditOutput>>({

packages/plugin-eslint/src/lib/runner/index.ts

@@ -2,7 +2,6 @@ import type {
   Audit,
   AuditOutput,
   AuditOutputs,
-  PersistConfig,
   PluginArtifactOptions,
   RunnerFunction,
 } from '@code-pushup/models';
@@ -23,15 +22,12 @@ export function createRunnerFunction(options: {
     slugs: audits.map(audit => audit.slug),
   };
 
-  return async ({ outputDir }: PersistConfig): Promise<AuditOutputs> => {
+  return async (): Promise<AuditOutputs> => {
     ui().logger.log(`ESLint plugin executing ${targets.length} lint targets`);
 
     const linterOutputs = artifacts
       ? await loadArtifacts(artifacts)
-      : await asyncSequential(
-          targets.map(target => ({ ...target, outputDir })),
-          lint,
-        );
+      : await asyncSequential(targets, lint);
     const lintResults = mergeLinterOutputs(linterOutputs);
     const failedAudits = lintResultsToAudits(lintResults);