refactor(models): polish models, mocks and comments

Author: BioPhoton

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { coreConfigSchema } from './core-config';
-import { mockCategory, mockConfig, mockPluginConfig } from '../../test';
+import { mockCategory, mockCoreConfig, mockPluginConfig } from '../../test';
 
 /*
  - plugin slug: es-lint
@@ -14,7 +14,7 @@ import { mockCategory, mockConfig, mockPluginConfig } from '../../test';
   */
 describe('CoreConfig', () => {
   it('should parse if configuration is valid', () => {
-    const cfg = mockConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
+    const cfg = mockCoreConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
     cfg.categories = [
       mockCategory({
         pluginSlug: 'test',
@@ -26,7 +26,7 @@ describe('CoreConfig', () => {
 
   it('should parse if configuration and groups are valid', () => {
     const pluginSlug = 'plg';
-    const cfg = mockConfig();
+    const cfg = mockCoreConfig();
     cfg.plugins = [
       mockPluginConfig({ pluginSlug, auditSlug: 'lcp', groupSlug: 'perf' }),
     ];
@@ -42,7 +42,7 @@ describe('CoreConfig', () => {
   });
 
   it('should throw if the category slugs are not unique', () => {
-    const cfg = mockConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
+    const cfg = mockCoreConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
     const duplicatedSlug = 'test';
     cfg.categories.push(
       mockCategory({
@@ -60,7 +60,7 @@ describe('CoreConfig', () => {
   });
 
   it('should throw if ref in a category does not exist in audits', () => {
-    const cfg = mockConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
+    const cfg = mockCoreConfig({ pluginSlug: 'test', auditSlug: ['a', 'b'] });
     cfg.categories = [
       mockCategory({
         pluginSlug: 'test',
@@ -74,7 +74,7 @@ describe('CoreConfig', () => {
   });
 
   it('should throw if ref in a category does not exist in groups', () => {
-    const cfg = mockConfig({
+    const cfg = mockCoreConfig({
       pluginSlug: 'test',
       auditSlug: ['a', 'b'],
       groupSlug: 'a',

packages/models/src/lib/implementation/schemas.ts

@@ -10,7 +10,7 @@ export function executionMetaSchema(
     descriptionDuration: string;
   } = {
     descriptionDate: 'Execution start date and time',
-    descriptionDuration: 'Execution duration',
+    descriptionDuration: 'Execution duration in ms',
   },
 ) {
   return z.object({
@@ -26,18 +26,15 @@ export function executionMetaSchema(
 export function slugSchema(
   description = 'Unique ID (human-readable, URL-safe)',
 ) {
-  return (
-    z
-      .string({ description })
-      // also validates ``and ` `
-      .regex(slugRegex, {
-        message:
-          'The slug has to follow the pattern [0-9a-z] followed by multiple optional groups of -[0-9a-z]. e.g. my-slug',
-      })
-      .max(128, {
-        message: 'slug can be max 128 characters long',
-      })
-  );
+  return z
+    .string({ description })
+    .regex(slugRegex, {
+      message:
+        'The slug has to follow the pattern [0-9a-z] followed by multiple optional groups of -[0-9a-z]. e.g. my-slug',
+    })
+    .max(128, {
+      message: 'slug can be max 128 characters long',
+    });
 }
 
 /**

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

@@ -17,7 +17,7 @@ import {
   hasMissingStrings,
 } from './implementation/utils';
 
-export const pluginMetadataSchema = packageVersionSchema({
+export const pluginSchema = packageVersionSchema({
   optional: true,
 })
   .merge(
@@ -110,7 +110,7 @@ export const pluginConfigSchema = z
         }),
       ),
   })
-  .merge(pluginMetadataSchema)
+  .merge(pluginSchema)
   // every listed group ref points to an audit within the plugin
   .refine(
     pluginCfg => !getMissingRefsFromGroups(pluginCfg),
@@ -190,10 +190,9 @@ export const issueSchema = z.object(
 );
 export type Issue = z.infer<typeof issueSchema>;
 
-export const auditOutputSchema = z
-  .object(
+export const auditOutputSchema = auditSchema.merge(
+  z.object(
     {
-      slug: slugSchema('References audit. ID (unique within pluginOutput)'),
       displayValue: z
         .string({ description: "Formatted value (e.g. '0.9 s', '2.1 MB')" })
         .optional(),
@@ -215,14 +214,8 @@ export const auditOutputSchema = z
         .optional(),
     },
     { description: 'Audit information' },
-  )
-  .merge(
-    metaSchema({
-      titleDescription: 'Audit title',
-      descriptionDescription: 'Audit description',
-      docsUrlDescription: 'Audit docs URL',
-    }),
-  );
+  ),
+);
 export type AuditOutput = z.infer<typeof auditOutputSchema>;
 
 export const auditOutputsSchema = z
@@ -237,20 +230,19 @@ export const auditOutputsSchema = z
   );
 export type AuditOutputs = z.infer<typeof auditOutputsSchema>;
 
-export const pluginOutputSchema = executionMetaSchema()
-  .merge(metaSchema()) // @TODO create reusable meta info for audit, plugin, category
+export const pluginOutputSchema = pluginSchema
+  .merge(executionMetaSchema()) // @TODO create reusable meta info for audit, plugin, category
   .merge(
-  z.object(
-    {
-      slug: slugSchema('Plugin slug'),
-      audits: auditOutputsSchema
-    },
-    {
-      description:
-        'List of JSON formatted audit output emitted by the runner process of a plugin',
-    },
-  ),
-);
+    z.object(
+      {
+        audits: auditOutputsSchema,
+      },
+      {
+        description:
+          'List of JSON formatted audit output emitted by the runner process of a plugin',
+      },
+    ),
+  );
 
 export type PluginOutput = z.infer<typeof pluginOutputSchema>;
 

packages/models/src/lib/report.ts

@@ -32,16 +32,21 @@ export type PluginReport = z.infer<typeof pluginReportSchema>;
 
 export const reportSchema = packageVersionSchema({
   versionDescription: 'NPM version of the CLI',
-}).merge(
-  z.object(
-    {
-      date: z.string({ description: 'Start date and time of the collect run' }),
-      duration: z.number({ description: 'Duration of the collect run in ms' }),
-      plugins: z.array(pluginReportSchema),
-    },
-    { description: 'Collect output data.' },
-  ),
-);
+})
+  .merge(
+    executionMetaSchema({
+      descriptionDate: 'Start date and time of the collect run',
+      descriptionDuration: 'Duration of the collect run in ms',
+    }),
+  )
+  .merge(
+    z.object(
+      {
+        plugins: z.array(pluginReportSchema),
+      },
+      { description: 'Collect output data' },
+    ),
+  );
 
 export type Report = z.infer<typeof reportSchema>;
 

packages/models/test/schema.mock.ts

@@ -10,6 +10,8 @@ import {
   AuditOutputs,
   AuditReport,
   UploadConfig,
+  AuditOutput,
+  Issue,
 } from '../src/index';
 
 const __pluginSlug__ = 'mock-plugin-slug';
@@ -77,7 +79,7 @@ export function mockAuditConfig(opt?: { auditSlug?: string }): Audit {
     title: auditSlug + ' title',
     description: 'audit description',
     docsUrl: 'http://www.my-docs.dev',
-  };
+  } satisfies Required<Audit>;
 }
 
 export function mockPersistConfig(opt?: Partial<PersistConfig>): PersistConfig {
@@ -87,7 +89,7 @@ export function mockPersistConfig(opt?: Partial<PersistConfig>): PersistConfig {
   return {
     outputPath,
     format,
-  };
+  } satisfies Required<PersistConfig>;
 }
 
 export function mockGroupConfig(opt?: {
@@ -113,7 +115,7 @@ export function mockGroupConfig(opt?: {
             weight: randWeight(),
           },
         ],
-  };
+  } satisfies Required<AuditGroup>;
 }
 
 export function mockCategory(opt?: {
@@ -172,8 +174,9 @@ export function mockCategory(opt?: {
       .map(word => word.slice(0, 1).toUpperCase() + word.slice(1))
       .join(' ')}`,
     description: `This is the category description of ${categorySlug}. Enjoy dummy text and data to the full.`,
+    docsUrl: 'https://category.dev?' + categorySlug,
     refs: categoryAuditRefs.concat(categoryGroupRefs),
-  };
+  } satisfies Required<CategoryConfig>;
 }
 
 export function mockReport(opt?: {
@@ -203,28 +206,25 @@ export function mockPluginReport(opt?: {
     date: new Date().toDateString(),
     duration: randDuration(),
     slug: pluginSlug,
-    docsUrl: `http://plugin.io/docs/${pluginSlug}`,
     title: 'Mock plugin Name',
+    description: 'Plugin description of ' + pluginSlug,
+    docsUrl: `http://plugin.io/docs/${pluginSlug}`,
     icon: 'socket',
     audits: Array.isArray(auditSlug)
       ? auditSlug.map(a => mockAuditReport({ auditSlug: a }))
       : [mockAuditReport({ auditSlug })],
-  };
+  } satisfies Required<PluginReport>;
 }
 
 export function mockAuditReport(opt?: { auditSlug: string }): AuditReport {
   let { auditSlug } = opt || {};
   auditSlug = auditSlug || __auditSlug__;
   return {
-    slug: auditSlug,
-    displayValue: 'mocked value',
-    value: Math.floor(Math.random() * 100),
-    score: Math.round(Math.random()),
-    title: auditSlug,
-  };
+    ...(mockAuditOutput({ auditSlug }) as Required<AuditOutput>),
+  } satisfies Required<AuditReport>;
 }
 
-export function mockConfig(opt?: {
+export function mockCoreConfig(opt?: {
   outputPath?: string;
   categorySlug?: string | string[];
   pluginSlug?: string | string[];
@@ -235,6 +235,7 @@ export function mockConfig(opt?: {
     opt || {};
   return {
     persist: mockPersistConfig({ outputPath }),
+    upload: mockUploadConfig(),
     plugins: Array.isArray(pluginSlug)
       ? pluginSlug.map(slug =>
           mockPluginConfig({ pluginSlug: slug, auditSlug, groupSlug }),
@@ -245,7 +246,7 @@ export function mockConfig(opt?: {
           mockCategory({ categorySlug: slug, auditSlug, groupSlug }),
         )
       : [mockCategory({ categorySlug, auditSlug, groupSlug })],
-  };
+  } satisfies Required<CoreConfig>;
 }
 
 export function mockUploadConfig(opt?: Partial<UploadConfig>): UploadConfig {
@@ -261,23 +262,40 @@ export function mockAuditOutputs(opt?: {
 }): AuditOutputs {
   let { auditSlug } = opt || {};
   auditSlug = auditSlug || 'mock-audit-output-slug';
-  const audits = Array.isArray(auditSlug)
-    ? auditSlug.map((slug, idx) => ({
-        slug,
-        title: 'Title of ' + slug,
-        value: idx,
-        displayValue: '',
-        score: 0,
-      }))
-    : [
-        {
-          slug: auditSlug,
-          title: 'Title of ' + auditSlug,
-          value: 12,
-          displayValue: '',
-          score: 0,
-        },
-      ];
+  return Array.isArray(auditSlug)
+    ? auditSlug.map((slug, idx) => mockAuditOutput({ auditSlug: slug }))
+    : [mockAuditOutput({ auditSlug })];
+}
+
+export function mockAuditOutput(opt?: { auditSlug: string }): AuditOutput {
+  let { auditSlug } = opt || {};
+  auditSlug = auditSlug || 'mock-audit-output-slug';
+  return {
+    slug: auditSlug,
+    title: 'Title of ' + auditSlug,
+    description: 'Description of ' + auditSlug,
+    docsUrl: 'https://audit.dev?' + auditSlug,
+    details: {
+      issues: [mockIssueOutput()],
+    },
+    value: 12,
+    displayValue: '',
+    score: 0,
+  } satisfies Required<AuditOutput>;
+}
 
-  return audits;
+export function mockIssueOutput(): Issue {
+  return {
+    severity: 'error',
+    message: '',
+    source: {
+      file: 'the-file.ts',
+      position: {
+        startLine: 1,
+        startColumn: 2,
+        endLine: 3,
+        endColumn: 4,
+      },
+    },
+  } satisfies Required<Issue>;
 }

packages/models/test/test-data/config-and-report-dummy.mock.ts

@@ -1,6 +1,6 @@
 import {
   mockCategory,
-  mockConfig,
+  mockCoreConfig,
   mockPluginConfig,
   mockReport,
 } from '../schema.mock';
@@ -10,7 +10,7 @@ const auditSlug0 = ['0a', '0b', '0c', '0d'];
 const auditSlug1 = ['1a', '1b', '1c'];
 const auditSlug2 = ['2a', '2b', '2c', '2d', '2e'];
 
-export const dummyConfig = mockConfig({ outputPath: 'out' });
+export const dummyConfig = mockCoreConfig({ outputPath: 'out' });
 dummyConfig.plugins = [
   mockPluginConfig({ pluginSlug: pluginSlug[0], auditSlug: auditSlug0 }),
   mockPluginConfig({ pluginSlug: pluginSlug[1], auditSlug: auditSlug1 }),

packages/models/test/test-data/config-and-report-lighthouse.mock.ts

@@ -1,5 +1,5 @@
 import { PluginConfig } from '../../src/index';
-import { mockConfig, mockReport } from '../schema.mock';
+import { mockCoreConfig, mockReport } from '../schema.mock';
 
 export const lighthousePlugin: () => PluginConfig = () =>
   ({
@@ -938,7 +938,7 @@ export const lighthousePlugin: () => PluginConfig = () =>
     ],
   } satisfies PluginConfig);
 
-export const lighthouseConfig = mockConfig();
+export const lighthouseConfig = mockCoreConfig();
 lighthouseConfig.plugins = [lighthousePlugin()];
 lighthouseConfig.categories = [
   {