feat: use formatted zod schema validation errors

matejchalk · matejchalk · commit 68fe123d7379 · 2025-10-29T13:43:32.000+01:00
diff --git a/packages/ci/src/lib/schemas.ts b/packages/ci/src/lib/schemas.ts
@@ -26,16 +26,18 @@ export const interpolatedSlugSchema = slugSchema.catch(ctx => {
   throw new ZodError(ctx.error.issues);
 });
 
-export const configPatternsSchema = z.object({
-  persist: persistConfigSchema.transform(persist => ({
-    ...DEFAULT_PERSIST_CONFIG,
-    ...persist,
-  })),
-  upload: uploadConfigSchema
-    .omit({ organization: true, project: true })
-    .extend({
-      organization: interpolatedSlugSchema,
-      project: interpolatedSlugSchema,
-    })
-    .optional(),
-});
+export const configPatternsSchema = z
+  .object({
+    persist: persistConfigSchema.transform(persist => ({
+      ...DEFAULT_PERSIST_CONFIG,
+      ...persist,
+    })),
+    upload: uploadConfigSchema
+      .omit({ organization: true, project: true })
+      .extend({
+        organization: interpolatedSlugSchema,
+        project: interpolatedSlugSchema,
+      })
+      .optional(),
+  })
+  .meta({ title: 'ConfigPatterns' });
diff --git a/packages/ci/src/lib/settings.ts b/packages/ci/src/lib/settings.ts
@@ -1,4 +1,4 @@
-import { ZodError, z } from 'zod';
+import { SchemaValidationError, validate } from '@code-pushup/models';
 import type { ConfigPatterns, Settings } from './models.js';
 import { configPatternsSchema } from './schemas.js';
 
@@ -32,17 +32,15 @@ export function parseConfigPatternsFromString(
 
   try {
     const json = JSON.parse(value);
-    return configPatternsSchema.parse(json);
+    return validate(configPatternsSchema, json);
   } catch (error) {
     if (error instanceof SyntaxError) {
       throw new TypeError(
         `Invalid JSON value for configPatterns input - ${error.message}`,
       );
     }
-    if (error instanceof ZodError) {
-      throw new TypeError(
-        `Invalid shape of configPatterns input:\n${z.prettifyError(error)}`,
-      );
+    if (error instanceof SchemaValidationError) {
+      throw new TypeError(`Invalid shape of configPatterns input:\n${error}`);
     }
     throw error;
   }
diff --git a/packages/cli/src/lib/implementation/core-config.int.test.ts b/packages/cli/src/lib/implementation/core-config.int.test.ts
@@ -1,3 +1,4 @@
+import ansis from 'ansis';
 import { describe, expect, vi } from 'vitest';
 import {
   type CoreConfig,
@@ -203,6 +204,11 @@ describe('parsing values from CLI and middleware', () => {
           middlewares: [{ middlewareFunction: coreConfigMiddleware }],
         },
       ).parseAsync(),
-    ).rejects.toThrow('invalid_type');
+    ).rejects.toThrow(`Invalid ${ansis.bold('UploadConfig')}
+✖ Invalid input: expected string, received undefined
+  → at server
+✖ Invalid input: expected string, received undefined
+  → at apiKey
+`);
   });
 });
diff --git a/packages/cli/src/lib/implementation/core-config.middleware.ts b/packages/cli/src/lib/implementation/core-config.middleware.ts
@@ -8,6 +8,7 @@ import {
   DEFAULT_PERSIST_OUTPUT_DIR,
   type Format,
   uploadConfigSchema,
+  validate,
 } from '@code-pushup/models';
 import type { CoreConfigCliOptions } from './core-config.model.js';
 import type { FilterOptions } from './filter.model.js';
@@ -58,10 +59,7 @@ export async function coreConfigMiddleware<
   const upload =
     rcUpload == null && cliUpload == null
       ? undefined
-      : uploadConfigSchema.parse({
-          ...rcUpload,
-          ...cliUpload,
-        });
+      : validate(uploadConfigSchema, { ...rcUpload, ...cliUpload });
 
   return {
     ...(config != null && { config }),
diff --git a/packages/cli/src/lib/yargs-cli.ts b/packages/cli/src/lib/yargs-cli.ts
@@ -8,7 +8,11 @@ import yargs, {
   type Options,
   type ParserConfigurationOptions,
 } from 'yargs';
-import { type PersistConfig, formatSchema } from '@code-pushup/models';
+import {
+  type PersistConfig,
+  formatSchema,
+  validate,
+} from '@code-pushup/models';
 import { TERMINAL_WIDTH } from '@code-pushup/utils';
 import {
   descriptionStyle,
@@ -37,9 +41,8 @@ export const yargsDecorator = {
  * returns configurable yargs CLI for code-pushup
  *
  * @example
- * yargsCli(hideBin(process.argv))
- *   // bootstrap CLI; format arguments
- *   .argv;
+ * // bootstrap CLI; format arguments
+ * yargsCli(hideBin(process.argv)).argv;
  */
 export function yargsCli<T = unknown>(
   argv: string[],
@@ -150,11 +153,13 @@ function validatePersistFormat(persist: PersistConfig) {
     if (persist.format != null) {
       persist.format
         .flatMap(format => format.split(','))
-        .forEach(format => formatSchema.parse(format));
+        .forEach(format => {
+          validate(formatSchema, format);
+        });
     }
     return true;
   } catch {
-    throw new Error(
+    throw new TypeError(
       `Invalid persist.format option. Valid options are: ${formatSchema.options.join(
         ', ',
       )}`,
diff --git a/packages/core/src/lib/collect-and-persist.ts b/packages/core/src/lib/collect-and-persist.ts
@@ -3,6 +3,7 @@ import {
   type CoreConfig,
   type PersistConfig,
   pluginReportSchema,
+  validate,
 } from '@code-pushup/models';
 import {
   isVerbose,
@@ -57,6 +58,6 @@ export async function collectAndPersistReports(
   // validate report and throw if invalid
   reportResult.plugins.forEach(plugin => {
     // Running checks after persisting helps while debugging as you can check the invalid output after the error is thrown
-    pluginReportSchema.parse(plugin);
+    validate(pluginReportSchema, plugin);
   });
 }
diff --git a/packages/core/src/lib/compare.ts b/packages/core/src/lib/compare.ts
@@ -7,6 +7,7 @@ import {
   type ReportsDiff,
   type UploadConfig,
   reportSchema,
+  validate,
 } from '@code-pushup/models';
 import {
   type Diff,
@@ -49,8 +50,8 @@ export async function compareReportFiles(
     readJsonFile(options?.after ?? defaultInputPath('after')),
   ]);
   const reports: Diff<Report> = {
-    before: reportSchema.parse(reportBefore),
-    after: reportSchema.parse(reportAfter),
+    before: validate(reportSchema, reportBefore),
+    after: validate(reportSchema, reportAfter),
   };
 
   const diff = compareReports(reports);
diff --git a/packages/core/src/lib/implementation/execute-plugin.ts b/packages/core/src/lib/implementation/execute-plugin.ts
@@ -34,16 +34,16 @@ import {
  *
  * @example
  * // plugin execution
- * const pluginCfg = pluginConfigSchema.parse({...});
+ * const pluginCfg = validate(pluginConfigSchema, {...});
  * const output = await executePlugin(pluginCfg);
  *
- *  @example
- *  // error handling
- *  try {
- *  await executePlugin(pluginCfg);
- *  } catch (e) {
- *  console.error(e.message);
- *  }
+ * @example
+ * // error handling
+ * try {
+ *   await executePlugin(pluginCfg);
+ * } catch (e) {
+ *   console.error(e.message);
+ * }
  */
 export async function executePlugin(
   pluginConfig: PluginConfig,
@@ -144,14 +144,14 @@ const wrapProgress = async (
  *
  * @example
  * // plugin execution
- * const plugins = [pluginConfigSchema.parse({...})];
+ * const plugins = [validate(pluginConfigSchema, {...})];
  *
  * @example
  * // error handling
  * try {
- * await executePlugins(plugins);
+ *   await executePlugins(plugins);
  * } catch (e) {
- * console.error(e.message); // Plugin output is invalid
+ *   console.error(e.message); // Plugin output is invalid
  * }
  *
  */
diff --git a/packages/models/README.md b/packages/models/README.md
@@ -65,8 +65,8 @@ Import the type definitions if using TypeScript:
 If you need runtime validation, use the underlying Zod schemas:
 
 ```ts
-import { coreConfigSchema } from '@code-pushup/models';
+import { coreConfigSchema, validate } from '@code-pushup/models';
 
 const json = JSON.parse(readFileSync('code-pushup.config.json'));
-const config = coreConfigSchema.parse(json); // throws ZodError if invalid
+const config = validate(coreConfigSchema, json); // throws SchemaValidationError if invalid
 ```
diff --git a/packages/models/src/lib/implementation/validate.ts b/packages/models/src/lib/implementation/validate.ts
@@ -28,7 +28,7 @@ export class SchemaValidationError extends Error {
 
 export function validate<T extends ZodType>(
   schema: T,
-  data: z.input<T>,
+  data: z.input<T> | {} | null | undefined, // loose autocomplete
   context: SchemaValidationContext = {},
 ): z.output<T> {
   const result = schema.safeParse(data);
diff --git a/packages/models/src/lib/implementation/validate.unit.test.ts b/packages/models/src/lib/implementation/validate.unit.test.ts
@@ -27,11 +27,9 @@ describe('validate', () => {
         dateOfBirth: z.iso.date().optional(),
       })
       .meta({ title: 'User' });
-    type User = z.infer<typeof userSchema>;
 
-    expect(() =>
-      validate(userSchema, { name: '', dateOfBirth: 'Jul 1, 1980' } as User),
-    ).toThrow(`Invalid ${ansis.bold('User')}
+    expect(() => validate(userSchema, { name: '', dateOfBirth: 'Jul 1, 1980' }))
+      .toThrow(`Invalid ${ansis.bold('User')}
 ✖ Too small: expected string to have >=1 characters
   → at name
 ✖ Invalid input: expected string, received undefined
diff --git a/packages/plugin-coverage/src/lib/coverage-plugin.ts b/packages/plugin-coverage/src/lib/coverage-plugin.ts
@@ -1,7 +1,12 @@
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import type { Audit, Group, PluginConfig } from '@code-pushup/models';
+import {
+  type Audit,
+  type Group,
+  type PluginConfig,
+  validate,
+} from '@code-pushup/models';
 import { capitalize } from '@code-pushup/utils';
 import {
   type CoveragePluginConfig,
@@ -32,7 +37,7 @@ import { coverageDescription, coverageTypeWeightMapper } from './utils.js';
 export async function coveragePlugin(
   config: CoveragePluginConfig,
 ): Promise<PluginConfig> {
-  const coverageConfig = coveragePluginConfigSchema.parse(config);
+  const coverageConfig = validate(coveragePluginConfigSchema, config);
 
   const audits = coverageConfig.coverageTypes.map(
     (type): Audit => ({
diff --git a/packages/plugin-eslint/src/lib/eslint-plugin.int.test.ts b/packages/plugin-eslint/src/lib/eslint-plugin.int.test.ts
@@ -1,3 +1,4 @@
+import ansis from 'ansis';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
@@ -129,7 +130,7 @@ describe('eslintPlugin', () => {
     await expect(
       // @ts-expect-error simulating invalid non-TS config
       eslintPlugin({ eslintrc: '.eslintrc.json' }),
-    ).rejects.toThrow('Failed parsing ESLint plugin config');
+    ).rejects.toThrow(`Invalid ${ansis.bold('ESLintPluginConfig')}`);
   });
 
   it("should throw if eslintrc file doesn't exist", async () => {
diff --git a/packages/plugin-js-packages/src/lib/utils.ts b/packages/plugin-js-packages/src/lib/utils.ts
@@ -1,12 +1,16 @@
+import { validate } from '@code-pushup/models';
 import {
   type JSPackagesPluginConfig,
   jsPackagesPluginConfigSchema,
 } from './config.js';
 import { derivePackageManager } from './package-managers/derive-package-manager.js';
 import { packageManagers } from './package-managers/package-managers.js';
 
-export async function normalizeConfig(config?: JSPackagesPluginConfig) {
-  const jsPackagesPluginConfig = jsPackagesPluginConfigSchema.parse(
+export async function normalizeConfig(
+  config: JSPackagesPluginConfig | undefined,
+) {
+  const jsPackagesPluginConfig = validate(
+    jsPackagesPluginConfigSchema,
     config ?? {},
   );
 
diff --git a/packages/plugin-jsdocs/src/lib/jsdocs-plugin.ts b/packages/plugin-jsdocs/src/lib/jsdocs-plugin.ts
@@ -1,4 +1,4 @@
-import type { PluginConfig } from '@code-pushup/models';
+import { type PluginConfig, validate } from '@code-pushup/models';
 import { type JsDocsPluginConfig, jsDocsPluginConfigSchema } from './config.js';
 import { PLUGIN_SLUG, groups } from './constants.js';
 import { createRunnerFunction } from './runner/runner.js';
@@ -31,7 +31,7 @@ export const PLUGIN_DOCS_URL =
  * @returns Plugin configuration.
  */
 export function jsDocsPlugin(config: JsDocsPluginConfig): PluginConfig {
-  const jsDocsConfig = jsDocsPluginConfigSchema.parse(config);
+  const jsDocsConfig = validate(jsDocsPluginConfigSchema, config);
   const scoreTargets = jsDocsConfig.scoreTargets;
 
   return {
diff --git a/packages/plugin-typescript/src/lib/typescript-plugin.ts b/packages/plugin-typescript/src/lib/typescript-plugin.ts
@@ -1,5 +1,5 @@
 import { createRequire } from 'node:module';
-import type { PluginConfig } from '@code-pushup/models';
+import { type PluginConfig, validate } from '@code-pushup/models';
 import { stringifyError } from '@code-pushup/utils';
 import { DEFAULT_TS_CONFIG, TYPESCRIPT_PLUGIN_SLUG } from './constants.js';
 import { createRunnerFunction } from './runner/runner.js';
@@ -50,7 +50,7 @@ function parseOptions(
   tsPluginOptions: TypescriptPluginOptions,
 ): TypescriptPluginConfig {
   try {
-    return typescriptPluginConfigSchema.parse(tsPluginOptions);
+    return validate(typescriptPluginConfigSchema, tsPluginOptions);
   } catch (error) {
     throw new Error(
       `Error parsing TypeScript Plugin options: ${stringifyError(error)}`,
diff --git a/packages/plugin-typescript/src/lib/typescript-plugin.unit.test.ts b/packages/plugin-typescript/src/lib/typescript-plugin.unit.test.ts
@@ -1,3 +1,4 @@
+import ansis from 'ansis';
 import { expect } from 'vitest';
 import { pluginConfigSchema } from '@code-pushup/models';
 import { AUDITS, GROUPS } from './constants.js';
@@ -35,7 +36,11 @@ describe('typescriptPlugin-config-object', () => {
       typescriptPlugin({
         tsconfig: 42,
       } as unknown as TypescriptPluginOptions),
-    ).rejects.toThrow(/invalid_type/);
+    ).rejects
+      .toThrow(`Error parsing TypeScript Plugin options: SchemaValidationError: Invalid ${ansis.bold('TypescriptPluginConfig')}
+✖ Invalid input: expected string, received number
+  → at tsconfig
+`);
   });
 
   it('should pass scoreTargets to PluginConfig when provided', async () => {
diff --git a/packages/utils/src/lib/git/git.commits-and-tags.ts b/packages/utils/src/lib/git/git.commits-and-tags.ts
@@ -1,5 +1,5 @@
 import { type LogOptions as SimpleGitLogOptions, simpleGit } from 'simple-git';
-import { type Commit, commitSchema } from '@code-pushup/models';
+import { type Commit, commitSchema, validate } from '@code-pushup/models';
 import { stringifyError } from '../errors.js';
 import { ui } from '../logging.js';
 import { isSemver } from '../semver.js';
@@ -13,7 +13,7 @@ export async function getLatestCommit(
       // git log -1 --pretty=format:"%H %s %an %aI" - See: https://git-scm.com/docs/pretty-formats
       format: { hash: '%H', message: '%s', author: '%an', date: '%aI' },
     });
-    return commitSchema.parse(log.latest);
+    return validate(commitSchema, log.latest);
   } catch (error) {
     ui().logger.error(stringifyError(error));
     return null;
diff --git a/packages/utils/src/lib/reports/load-report.ts b/packages/utils/src/lib/reports/load-report.ts
@@ -4,6 +4,7 @@ import {
   type PersistConfig,
   type Report,
   reportSchema,
+  validate,
 } from '@code-pushup/models';
 import {
   ensureDirectoryExists,
@@ -24,9 +25,10 @@ export async function loadReport<T extends Format>(
 
   if (format === 'json') {
     const content = await readJsonFile(filePath);
-    return reportSchema.parse(content) as LoadedReportFormat<T>;
+    const report: Report = validate(reportSchema, content);
+    return report as LoadedReportFormat<T>;
   }
 
-  const text = await readTextFile(filePath);
+  const text: string = await readTextFile(filePath);
   return text as LoadedReportFormat<T>;
 }
diff --git a/testing/test-utils/src/lib/utils/dynamic-mocks/config.mock.ts b/testing/test-utils/src/lib/utils/dynamic-mocks/config.mock.ts
diff --git a/testing/test-utils/src/lib/utils/dynamic-mocks/persist-config.mock.ts b/testing/test-utils/src/lib/utils/dynamic-mocks/persist-config.mock.ts
diff --git a/testing/test-utils/src/lib/utils/dynamic-mocks/plugin-config.mock.ts b/testing/test-utils/src/lib/utils/dynamic-mocks/plugin-config.mock.ts
diff --git a/testing/test-utils/src/lib/utils/dynamic-mocks/upload-config.mock.ts b/testing/test-utils/src/lib/utils/dynamic-mocks/upload-config.mock.ts
