feat(models): setup types and parser with zod

Author: BioPhoton

package.json

@@ -8,7 +8,8 @@
     "dist/packages/*"
   ],
   "dependencies": {
-    "bundle-require": "^4.0.1"
+    "bundle-require": "^4.0.1",
+    "zod": "^3.22.1"
   },
   "devDependencies": {
     "@nx/esbuild": "16.7.4",

packages/models/.eslintrc.json

@@ -0,0 +1,18 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    }
+  ]
+}

packages/models/README.md

@@ -0,0 +1,14 @@
+# models
+
+Model definitions for the CLI configuration as well as plugin types and respective parser.
+
+## Usage
+
+```ts
+import { CoreConfigSchema, pluginConfigSchema } from '@qm/cli-models';
+
+export default {
+  // ...
+  plugins: [pluginConfigSchema.parse({ ... })],
+} satisfies CoreConfigSchema;
+```

packages/models/project.json

@@ -0,0 +1,19 @@
+{
+  "name": "@quality-metrics/cli/models",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "libs/cli-models/src",
+  "projectType": "library",
+  "targets": {
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["libs/cli-models/**/*.ts"]
+      }
+    },
+    "generate-schema-from-type": {
+      "command": "npx json-schema-to-zod -s libs/cli-models/schema.json -t libs/cli/schema.ts --deref"
+    }
+  },
+  "tags": ["scope:cli", "type:util"]
+}

packages/models/src/index.ts

@@ -0,0 +1,14 @@
+export { coreConfigSchema, CoreConfigSchema } from './lib/core-config';
+export { uploadConfigSchema, UploadConfigSchema } from './lib/upload';
+export { pluginConfigSchema, PluginConfigSchema } from './lib/plugins';
+export { runnerOutputSchema, RunnerOutputSchema } from './lib/plugin-output';
+export { persistConfigSchema, PersistConfigSchema } from './lib/persist';
+export {
+  categoryConfigSchema,
+  CategoryConfigSchema,
+} from './lib/category-config';
+export { budgetSchema, BudgetSchema } from './lib/budgets';
+export {
+  globalCliArgsSchema,
+  GlobalCliArgsSchema,
+} from './lib/global-cli-options';

packages/models/src/lib/budgets.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+
+/**
+ * Define Zod schema for the Budget type
+ *
+ * @example
+ *
+ * // Type assertion for valid budget data
+ * const validBudget = {
+ *   ref: 'eslint#max-lines',
+ *   minScore: 0.8,
+ *   maxWarnings: 5,
+ *   maxValue: 1000,
+ * } as z.infer<typeof budgetSchema>;
+ *
+ * // Validate the data against the schema
+ * const validationResult = budgetSchema.safeParse(validBudget);
+ *
+ * if (validationResult.success) {
+ *   console.log('Valid budget:', validationResult.data);
+ * } else {
+ *   console.error('Invalid budget:', validationResult.error);
+ * }
+ *
+ **/
+export const budgetSchema = z.object({
+  ref: z.string({
+    description:
+      "reference to audit ('eslint#max-lines') or category ('categories:performance')",
+  }),
+  minScore: z
+    .number({
+      description: 'fail assertion if score too low',
+    })
+    .min(0)
+    .max(1)
+    .optional(),
+  maxWarnings: z
+    .number({
+      description: 'fail assertion if too many warnings',
+    })
+    .optional(),
+  maxValue: z
+    .number({
+      description: 'fail assertion if value too high',
+    })
+    .optional(),
+});
+
+export type BudgetSchema = z.infer<typeof budgetSchema>;

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

@@ -0,0 +1,60 @@
+import {z} from 'zod';
+
+/**
+ *
+ * Define Zod schema for the CategoryConfig type
+ *
+ * @example
+ *
+ * // Example data for the CategoryConfig type
+ * const categoryConfigData = {
+ *   slug: 'performance',
+ *   title: 'Performance Metrics',
+ *   description: 'This category includes performance-related metrics.',
+ *   metrics: [
+ *     { ref: 'eslint#max-lines', weight: 0.5 },
+ *     { ref: 'categories:lhci#performance', weight: 0.8 },
+ *   ],
+ * };
+ *
+ * // Validate the data against the schema
+ * const validationResult = categoryConfigSchema.safeParse(categoryConfigData);
+ *
+ * if (validationResult.success) {
+ *   console.log('Valid category config:', validationResult.data);
+ * } else {
+ *   console.error('Invalid category config:', validationResult.error);
+ * }
+ */
+export const categoryConfigSchema = z.object(
+  {
+    slug: z.string({
+      description: 'Human-readable unique ID',
+    }),
+    title: z.string({
+      description: 'Display name for the category',
+    }),
+    description: z
+      .string({
+        description: 'Optional description in Markdown format',
+      })
+      .optional(),
+    metrics: z.array(
+      z.object({
+        ref: z.string({
+          description:
+            "Reference to a plugin's audit (e.g. 'eslint#max-lines') or category (e.g. 'categories:lhci#performance')",
+        }),
+        weight: z.number({
+          description:
+            'Coefficient for the given score (use weight 0 if only for display)',
+        }).default(0).optional(),
+      }, {description: "Array of metrics associated with the category"})
+    ),
+  },
+  {
+    description: 'Weighted references to plugin-specific audits/categories',
+  },
+);
+
+export type CategoryConfigSchema = z.infer<typeof categoryConfigSchema>;

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

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { pluginConfigSchema } from './plugins';
+import { categoryConfigSchema } from './category-config';
+import { uploadConfigSchema } from './upload';
+import { budgetSchema } from './budgets';
+import { persistConfigSchema } from './persist';
+
+/**
+ * Define Zod schema for the CoreConfig type
+ *
+ * @example
+ *
+ * // Example data for the CoreConfig type
+ * const coreConfigData = {
+ *   // ... populate with example data ...
+ * };
+ *
+ * // Validate the data against the schema
+ * const validationResult = coreConfigSchema.safeParse(coreConfigData);
+ *
+ * if (validationResult.success) {
+ *   console.log('Valid plugin config:', validationResult.data);
+ * } else {
+ *   console.error('Invalid plugin config:', validationResult.error);
+ * }
+ */
+export const coreConfigSchema = z.object({
+  plugins: z.array(pluginConfigSchema, {
+    description: 'list of plugins to be used (built-in, 3rd party, or custom)',
+  }),
+  /** portal configuration for persisting results */
+  persist: persistConfigSchema,
+  /** portal configuration for uploading results */
+  upload: uploadConfigSchema.optional(),
+  categories: z.array(categoryConfigSchema, {
+    description: 'categorization of individual audits',
+  }),
+  budgets: z
+    .array(budgetSchema, {
+      description: 'budget rules for assertion',
+    })
+    .optional(),
+});
+
+export type CoreConfigSchema = z.infer<typeof coreConfigSchema>;

packages/models/src/lib/global-cli-options.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+/**
+ * Define Zod schema for the GlobalCliArgs type
+ *
+ * @example
+ *
+ * // Example data for the GlobalCliArgs type
+ * const uploadConfigData = {
+ *   server: 'https://example.com/api',
+ *   apiKey: 'your-api-key',
+ * };
+ *
+ * // Validate the data against the schema
+ * const validationResult = globalCliArgsSchema.safeParse(globalCliArgsData);
+ *
+ * if (validationResult.success) {
+ *   console.log('Valid config:', validationResult.data);
+ * } else {
+ *   console.error('Invalid config:', validationResult.error);
+ * }
+ *
+ */
+export const globalCliArgsSchema = z.object({
+  interactive: z
+    .boolean({
+      description:
+        'flag if interactivity should be considered. Useful for CI runs.',
+    })
+    .default(true),
+  verbose: z
+    .boolean({
+      description: 'Outputs additional information for a run',
+    })
+    .default(false),
+  configPath: z
+    .string({
+      description: "Path to config.js. defaults to 'cpu-config.js'",
+    })
+    .optional()
+    .default('cpu-config.js'),
+});
+
+export type GlobalCliArgsSchema = z.infer<typeof globalCliArgsSchema>;

packages/models/src/lib/persist.ts

@@ -0,0 +1,30 @@
+import {z} from 'zod';
+
+/**
+ * Define Zod schema for the PersistConfig type
+ *
+ * @example
+ *
+ * // Example data for the UploadConfig type
+ * const uploadConfigData = {
+ *   server: 'https://example.com/api',
+ *   apiKey: 'your-api-key',
+ * };
+ *
+ * // Validate the data against the schema
+ * const validationResult = uploadConfigSchema.safeParse(uploadConfigData);
+ *
+ * if (validationResult.success) {
+ *   console.log('Valid persist config:', validationResult.data);
+ * } else {
+ *   console.error('Invalid persist config:', validationResult.error);
+ * }
+ *
+ */
+export const persistConfigSchema = z.object({
+  outputPath: z.string({
+    description: 'Artefacts folder',
+  }),
+});
+
+export type PersistConfigSchema = z.infer<typeof persistConfigSchema>;