feat(models): setup types and parser with zod

examples/cli-e2e/tests/cli.spec.ts

@@ -1,3 +1,4 @@
+import { describe, it, expect, beforeAll } from 'vitest';
 import { cli } from '@quality-metrics/cli';
 import { execSync } from 'child_process';
 

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,25 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": ["error"]
+      }
+    }
+  ]
+}

packages/models/README.md

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

packages/models/project.json

@@ -0,0 +1,24 @@
+{
+  "name": "models",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/models/src",
+  "projectType": "library",
+  "targets": {
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["packages/models/**/*.ts"]
+      }
+    },
+    "test": {
+      "executor": "@nx/vite:test",
+      "outputs": ["{workspaceRoot}/coverage/packages/cli"],
+      "options": {
+        "passWithNoTests": true,
+        "reportsDirectory": "../../coverage/packages/cli"
+      }
+    }
+  },
+  "tags": []
+}

packages/models/src/index.ts

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

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

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { mockCategory } from './implementation/helpers.mock';
+import { categoryConfigSchema } from './category-config';
+
+describe('categoryConfigSchema', () => {
+  it('should parse if configuration with audit refs is valid', () => {
+    const cfg = mockCategory({ auditRefOrGroupRef: ['test#a', 'test#b'] });
+    expect(() => categoryConfigSchema.parse(cfg)).not.toThrow();
+  });
+
+  it('should parse if configuration with group refs is valid', () => {
+    const cfg = mockCategory({ auditRefOrGroupRef: ['es-lint#group:base'] });
+    expect(() => categoryConfigSchema.parse(cfg)).not.toThrow();
+  });
+
+  it('should throw if category slug has a invalid pattern', () => {
+    const invalidCategorySlug = '-invalid-category-slug';
+    const cfg = mockCategory({ categorySlug: invalidCategorySlug });
+
+    expect(() => categoryConfigSchema.parse(cfg)).toThrow(
+      `slug has to follow the pattern`,
+    );
+  });
+
+  it('should throw if audit ref in metrics is invalid', () => {
+    const invalidAuditRef = 'no-any';
+    const cfg = mockCategory({ auditRefOrGroupRef: [invalidAuditRef] });
+
+    expect(() => categoryConfigSchema.parse(cfg)).toThrow(
+      `ref has to follow the pattern`,
+    );
+  });
+
+  it('should throw if duplicate refs to audits or groups in metrics are given', () => {
+    const duplicatedSlug = 'test#a';
+    const cfg = mockCategory({
+      auditRefOrGroupRef: [duplicatedSlug, duplicatedSlug],
+    });
+    expect(() => categoryConfigSchema.parse(cfg)).toThrow(
+      'the following audit or group refs are duplicates',
+    );
+  });
+});

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

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import {
+  refSchema,
+  descriptionSchema,
+  slugSchema,
+  titleSchema,
+  weightSchema,
+} from './implementation/schemas';
+import { errorItems, hasDuplicateStrings } from './implementation/utils';
+
+/**
+ *
+ * Define Zod schema for the CategoryConfig type
+ *
+ * @example
+ *
+ * // Example data for the CategoryConfig type
+ * const data = {
+ *  // ...
+ * };
+ *
+ * // Validate the data against the schema
+ * const validationResult = categoryConfigSchema.safeParse(data);
+ *
+ * if (validationResult.success) {
+ *   console.log('Valid category config:', validationResult.data);
+ * } else {
+ *   console.error('Invalid category config:', validationResult.error);
+ * }
+ */
+export const categoryConfigSchema = z.object(
+  {
+    slug: slugSchema(),
+    title: titleSchema('Display name for the category '),
+    description: descriptionSchema('Optional description in Markdown format'),
+    metrics: z
+      .array(
+        z.object(
+          {
+            ref: refSchema(
+              "Reference to a plugin's audit (e.g. 'eslint#max-lines') or group (e.g. 'lhci#group:performance')",
+            ),
+            weight: weightSchema(),
+          },
+          { description: 'Array of metrics associated with the category' },
+        ),
+      )
+      // metrics have unique refs to audits or groups within a category
+      .refine(
+        metrics => !getDuplicateRefsInCategoryMetrics(metrics),
+        metrics => ({
+          message: duplicateRefsInCategoryMetricsErrorMsg(metrics),
+        }),
+      ),
+  },
+  {
+    description: 'Weighted references to plugin-specific audits/categories',
+  },
+);
+
+export type CategoryConfigSchema = z.infer<typeof categoryConfigSchema>;
+
+// helper for validator: categories have unique refs to audits or groups
+export function duplicateRefsInCategoryMetricsErrorMsg(metrics) {
+  const duplicateRefs = getDuplicateRefsInCategoryMetrics(metrics);
+  return `In the categories, the following audit or group refs are duplicates: ${errorItems(
+    duplicateRefs,
+  )}`;
+}
+function getDuplicateRefsInCategoryMetrics(metrics) {
+  return hasDuplicateStrings(metrics.map(({ ref }) => ref));
+}

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

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+import {
+  mockCategory,
+  mockConfig,
+  mockPluginConfig,
+} from './implementation/helpers.mock';
+import { coreConfigSchema } from './core-config';
+
+/*
+ - plugin slug: es-lint
+ - audit slug: no-any
+ - group slug: basics
+   - audit: no-any
+ - category: best-practices
+
+ - from category to audit: es-lint#no-any
+ - from category to group: es-lint#group:basics
+  */
+describe('CoreConfig', () => {
+  it('should parse if configuration is valid', () => {
+    const cfg = mockConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
+    cfg.categories.push(
+      mockCategory({ auditRefOrGroupRef: ['test#a', 'test#b'] }),
+    );
+    expect(() => coreConfigSchema.parse(cfg)).not.toThrow();
+  });
+
+  it('should parse if configuration and groups are valid', () => {
+    const pluginSlug = 'plg';
+    const cfg = mockConfig();
+    cfg.plugins = [
+      mockPluginConfig({ pluginSlug, auditSlug: 'lcp', groupSlug: 'perf' }),
+    ];
+    cfg.categories = [
+      mockCategory({ auditRefOrGroupRef: ['plg#lcp', 'plg#group:perf'] }),
+    ];
+    // In the categories, the following plugin refs do not exist in the provided plugins: test#group:group-slug
+    expect(() => coreConfigSchema.parse(cfg)).not.toThrow();
+  });
+
+  it('should throw if the category slugs are not unique', () => {
+    const cfg = mockConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
+    const duplicatedSlug = 'test';
+    cfg.categories.push(
+      mockCategory({ categorySlug: 'test', auditRefOrGroupRef: ['test#a'] }),
+      mockCategory({ categorySlug: 'test', auditRefOrGroupRef: ['test#b'] }),
+    );
+    expect(() => coreConfigSchema.parse(cfg)).toThrow(
+      `In the categories, the following slugs are duplicated: ${duplicatedSlug}`,
+    );
+  });
+
+  it('should throw if ref in a category does not exist in audits', () => {
+    const cfg = mockConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
+    const missingSlug = 'missing-plugin-slug-in-category#auditref';
+    cfg.categories.push(
+      mockCategory({
+        categorySlug: 'test',
+        auditRefOrGroupRef: [`${missingSlug}`],
+      }),
+    );
+    expect(() => coreConfigSchema.parse(cfg)).toThrow(
+      `In the categories, the following plugin refs do not exist in the provided plugins: ${missingSlug}`,
+    );
+  });
+
+  it('should throw if ref in a category does not exist in groups', () => {
+    const cfg = mockConfig({
+      pluginSlug: 'test',
+      auditSlug: ['a', 'b'],
+      groupSlug: 'test#a',
+    });
+    const missingSlug = 'missing-plugin-slug-in-category#groups:auditref';
+    cfg.categories.push(
+      mockCategory({
+        categorySlug: 'test',
+        auditRefOrGroupRef: [`${missingSlug}`],
+      }),
+    );
+    expect(() => coreConfigSchema.parse(cfg)).toThrow(
+      `In the categories, the following plugin refs do not exist in the provided plugins: ${missingSlug}`,
+    );
+  });
+});