@code-pushup/models 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @code-pushup/models
+
+**Model definitions and validators** for the [Code PushUp CLI](../cli/README.md).
+
+## Setup
+
+If you've already installed another `@code-pushup/*` package, then you may have already installed `@code-pushup/models` indirectly.
+
+If not, you can always install it separately:
+
+```sh
+npm install --save-dev @code-pushup/models
+```
+
+```sh
+yarn add --dev @code-pushup/models
+```
+
+```sh
+pnpm add --save-dev @code-pushup/models
+```
+
+## Usage
+
+Import the type definitions if using TypeScript:
+
+- in `code-pushup.config.ts`:
+
+  ```ts
+  import type { CoreConfig } from '@code-pushup/models';
+
+  export default {
+    // ... this is type-checked ...
+  } satisfies CoreConfig;
+  ```
+
+- in custom plugin:
+
+  ```ts
+  import type { PluginConfig } from '@code-pushup/models';
+
+  export default function myCustomPlugin(): PluginConfig {
+    return {
+      // ... this is type-checked ...
+    };
+  }
+  ```
+
+  ```ts
+  import type { AuditOutput } from '@code-pushup/models';
+
+  async function myCustomPluginRunner() {
+    const audits: AuditOutput[] = await collectAudits();
+
+    await writeFile(RUNNER_OUTPUT_FILE, JSON.strinfigy(audits));
+  }
+  ```
+
+If you need runtime validation, use the underlying Zod schemas:
+
+```ts
+import { coreConfigSchema } from '@code-pushup/models';
+
+const json = JSON.parse(readFileSync('code-pushup.config.json'));
+const config = coreConfigSchema.parse(json); // throws ZodError if invalid
+```

package/index.js

@@ -0,0 +1,543 @@
+// packages/models/src/lib/category-config.ts
+import { z as z2 } from "zod";
+
+// packages/models/src/lib/implementation/schemas.ts
+import { z } from "zod";
+import { MATERIAL_ICONS } from "@code-pushup/portal-client";
+
+// packages/models/src/lib/implementation/utils.ts
+var slugRegex = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var filenameRegex = /^(?!.*[ \\/:*?"<>|]).+$/;
+function hasDuplicateStrings(strings) {
+  const uniqueStrings = Array.from(new Set(strings));
+  const duplicatedStrings = strings.filter(
+    /* @__PURE__ */ ((i) => (v) => uniqueStrings[i] !== v || !++i)(0)
+  );
+  return duplicatedStrings.length === 0 ? false : duplicatedStrings;
+}
+function hasMissingStrings(toCheck, existing) {
+  const nonExisting = toCheck.filter((s) => !existing.includes(s));
+  return nonExisting.length === 0 ? false : nonExisting;
+}
+function errorItems(items, transform = (items2) => items2.join(", ")) {
+  const paredItems = items ? items : [];
+  return transform(paredItems);
+}
+function exists(value) {
+  return value != null;
+}
+
+// packages/models/src/lib/implementation/schemas.ts
+function executionMetaSchema(options = {
+  descriptionDate: "Execution start date and time",
+  descriptionDuration: "Execution duration in ms"
+}) {
+  return z.object({
+    date: z.string({ description: options.descriptionDate }),
+    duration: z.number({ description: options.descriptionDuration })
+  });
+}
+function slugSchema(description = "Unique ID (human-readable, URL-safe)") {
+  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"
+  });
+}
+function descriptionSchema(description = "Description (markdown)") {
+  return z.string({ description }).max(65536).optional();
+}
+function docsUrlSchema(description = "Documentation site") {
+  return urlSchema(description).optional().or(z.string().max(0));
+}
+function urlSchema(description) {
+  return z.string({ description }).url();
+}
+function titleSchema(description = "Descriptive name") {
+  return z.string({ description }).max(256);
+}
+function metaSchema(options) {
+  const {
+    descriptionDescription,
+    titleDescription,
+    docsUrlDescription,
+    description
+  } = options || {};
+  return z.object(
+    {
+      title: titleSchema(titleDescription),
+      description: descriptionSchema(descriptionDescription),
+      docsUrl: docsUrlSchema(docsUrlDescription)
+    },
+    { description }
+  );
+}
+function filePathSchema(description) {
+  return z.string({ description }).trim().min(1, { message: "path is invalid" });
+}
+function fileNameSchema(description) {
+  return z.string({ description }).trim().regex(filenameRegex, {
+    message: `The filename has to be valid`
+  }).min(1, { message: "file name is invalid" });
+}
+function positiveIntSchema(description) {
+  return z.number({ description }).int().nonnegative();
+}
+function packageVersionSchema(options) {
+  let { versionDescription, optional } = options || {};
+  versionDescription = versionDescription || "NPM version of the package";
+  optional = !!optional;
+  const packageSchema = z.string({ description: "NPM package name" });
+  const versionSchema = z.string({ description: versionDescription });
+  return z.object(
+    {
+      packageName: optional ? packageSchema.optional() : packageSchema,
+      version: optional ? versionSchema.optional() : versionSchema
+    },
+    { description: "NPM package name and version of a published package" }
+  );
+}
+function weightSchema(description = "Coefficient for the given score (use weight 0 if only for display)") {
+  return positiveIntSchema(description);
+}
+function weightedRefSchema(description, slugDescription) {
+  return z.object(
+    {
+      slug: slugSchema(slugDescription),
+      weight: weightSchema("Weight used to calculate score")
+    },
+    { description }
+  );
+}
+function scorableSchema(description, refSchema, duplicateCheckFn, duplicateMessageFn) {
+  return z.object(
+    {
+      slug: slugSchema('Human-readable unique ID, e.g. "performance"'),
+      refs: z.array(refSchema).refine(
+        (refs) => !duplicateCheckFn(refs),
+        (refs) => ({
+          message: duplicateMessageFn(refs)
+        })
+      )
+    },
+    { description }
+  );
+}
+var materialIconSchema = z.enum(
+  MATERIAL_ICONS,
+  { description: "Icon from VSCode Material Icons extension" }
+);
+
+// packages/models/src/lib/category-config.ts
+var categoryRefSchema = weightedRefSchema(
+  "Weighted references to audits and/or groups for the category",
+  "Slug of an audit or group (depending on `type`)"
+).merge(
+  z2.object({
+    type: z2.enum(["audit", "group"], {
+      description: "Discriminant for reference kind, affects where `slug` is looked up"
+    }),
+    plugin: slugSchema(
+      "Plugin slug (plugin should contain referenced audit or group)"
+    )
+  })
+);
+var categoryConfigSchema = scorableSchema(
+  "Category with a score calculated from audits and groups from various plugins",
+  categoryRefSchema,
+  getDuplicateRefsInCategoryMetrics,
+  duplicateRefsInCategoryMetricsErrorMsg
+).merge(
+  metaSchema({
+    titleDescription: "Category Title",
+    docsUrlDescription: "Category docs URL",
+    descriptionDescription: "Category description",
+    description: "Meta info for category"
+  })
+).merge(
+  z2.object({
+    isBinary: z2.boolean({
+      description: 'Is this a binary category (i.e. only a perfect score considered a "pass")?'
+    }).optional()
+  })
+);
+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(({ slug, type, plugin }) => `${type} :: ${plugin} / ${slug}`)
+  );
+}
+
+// packages/models/src/lib/core-config.ts
+import { z as z11 } from "zod";
+
+// packages/models/src/lib/persist-config.ts
+import { z as z3 } from "zod";
+var formatSchema = z3.enum(["json", "md"]);
+var persistConfigSchema = z3.object({
+  outputDir: filePathSchema("Artifacts folder"),
+  filename: fileNameSchema("Artifacts file name (without extension)").default(
+    "report"
+  ),
+  format: z3.array(formatSchema).default(["json"]).optional()
+  // @TODO remove default or optional value and otherwise it will not set defaults.
+});
+
+// packages/models/src/lib/plugin-config.ts
+import { z as z9 } from "zod";
+
+// packages/models/src/lib/plugin-config-audits.ts
+import { z as z4 } from "zod";
+var auditSchema = z4.object({
+  slug: slugSchema("ID (unique within plugin)")
+}).merge(
+  metaSchema({
+    titleDescription: "Descriptive name",
+    descriptionDescription: "Description (markdown)",
+    docsUrlDescription: "Link to documentation (rationale)",
+    description: "List of scorable metrics for the given plugin"
+  })
+);
+var pluginAuditsSchema = z4.array(auditSchema, {
+  description: "List of audits maintained in a plugin"
+}).refine(
+  (auditMetadata) => !getDuplicateSlugsInAudits(auditMetadata),
+  (auditMetadata) => ({
+    message: duplicateSlugsInAuditsErrorMsg(auditMetadata)
+  })
+);
+function duplicateSlugsInAuditsErrorMsg(audits) {
+  const duplicateRefs = getDuplicateSlugsInAudits(audits);
+  return `In plugin audits the slugs are not unique: ${errorItems(
+    duplicateRefs
+  )}`;
+}
+function getDuplicateSlugsInAudits(audits) {
+  return hasDuplicateStrings(audits.map(({ slug }) => slug));
+}
+
+// packages/models/src/lib/plugin-config-groups.ts
+import { z as z5 } from "zod";
+var auditGroupRefSchema = weightedRefSchema(
+  "Weighted references to audits",
+  "Reference slug to an audit within this plugin (e.g. 'max-lines')"
+);
+var auditGroupSchema = scorableSchema(
+  'An audit group aggregates a set of audits into a single score which can be referenced from a category. E.g. the group slug "performance" groups audits and can be referenced in a category',
+  auditGroupRefSchema,
+  getDuplicateRefsInGroups,
+  duplicateRefsInGroupsErrorMsg
+).merge(
+  metaSchema({
+    titleDescription: "Descriptive name for the group",
+    descriptionDescription: "Description of the group (markdown)",
+    docsUrlDescription: "Group documentation site",
+    description: "Group metadata"
+  })
+);
+var auditGroupsSchema = z5.array(auditGroupSchema, {
+  description: "List of groups"
+}).optional().refine(
+  (groups) => !getDuplicateSlugsInGroups(groups),
+  (groups) => ({
+    message: duplicateSlugsInGroupsErrorMsg(groups)
+  })
+);
+function duplicateRefsInGroupsErrorMsg(groupAudits) {
+  const duplicateRefs = getDuplicateRefsInGroups(groupAudits);
+  return `In plugin groups the audit refs are not unique: ${errorItems(
+    duplicateRefs
+  )}`;
+}
+function getDuplicateRefsInGroups(groupAudits) {
+  return hasDuplicateStrings(
+    groupAudits.map(({ slug: ref }) => ref).filter(exists)
+  );
+}
+function duplicateSlugsInGroupsErrorMsg(groups) {
+  const duplicateRefs = getDuplicateSlugsInGroups(groups);
+  return `In groups the slugs are not unique: ${errorItems(duplicateRefs)}`;
+}
+function getDuplicateSlugsInGroups(groups) {
+  return Array.isArray(groups) ? hasDuplicateStrings(groups.map(({ slug }) => slug)) : false;
+}
+
+// packages/models/src/lib/plugin-config-runner.ts
+import { z as z8 } from "zod";
+
+// packages/models/src/lib/plugin-process-output.ts
+import { z as z7 } from "zod";
+
+// packages/models/src/lib/plugin-process-output-audit-issue.ts
+import { z as z6 } from "zod";
+var sourceFileLocationSchema = z6.object(
+  {
+    file: filePathSchema("Relative path to source file in Git repo"),
+    position: z6.object(
+      {
+        startLine: positiveIntSchema("Start line"),
+        startColumn: positiveIntSchema("Start column").optional(),
+        endLine: positiveIntSchema("End line").optional(),
+        endColumn: positiveIntSchema("End column").optional()
+      },
+      { description: "Location in file" }
+    ).optional()
+  },
+  { description: "Source file location" }
+);
+var issueSeveritySchema = z6.enum(["info", "warning", "error"], {
+  description: "Severity level"
+});
+var issueSchema = z6.object(
+  {
+    message: z6.string({ description: "Descriptive error message" }).max(512),
+    severity: issueSeveritySchema,
+    source: sourceFileLocationSchema.optional()
+  },
+  { description: "Issue information" }
+);
+
+// packages/models/src/lib/plugin-process-output.ts
+var auditOutputSchema = z7.object(
+  {
+    slug: slugSchema("Reference to audit"),
+    displayValue: z7.string({ description: "Formatted value (e.g. '0.9 s', '2.1 MB')" }).optional(),
+    value: positiveIntSchema("Raw numeric value"),
+    score: z7.number({
+      description: "Value between 0 and 1"
+    }).min(0).max(1),
+    details: z7.object(
+      {
+        issues: z7.array(issueSchema, { description: "List of findings" })
+      },
+      { description: "Detailed information" }
+    ).optional()
+  },
+  { description: "Audit information" }
+);
+var auditOutputsSchema = z7.array(auditOutputSchema, {
+  description: "List of JSON formatted audit output emitted by the runner process of a plugin"
+}).refine(
+  (audits) => !getDuplicateSlugsInAudits2(audits),
+  (audits) => ({ message: duplicateSlugsInAuditsErrorMsg2(audits) })
+);
+function duplicateSlugsInAuditsErrorMsg2(audits) {
+  const duplicateRefs = getDuplicateSlugsInAudits2(audits);
+  return `In plugin audits the slugs are not unique: ${errorItems(
+    duplicateRefs
+  )}`;
+}
+function getDuplicateSlugsInAudits2(audits) {
+  return hasDuplicateStrings(audits.map(({ slug }) => slug));
+}
+
+// packages/models/src/lib/plugin-config-runner.ts
+var outputTransformSchema = z8.function().args(z8.unknown()).returns(z8.union([auditOutputsSchema, z8.promise(auditOutputsSchema)]));
+var runnerConfigSchema = z8.object(
+  {
+    command: z8.string({
+      description: "Shell command to execute"
+    }),
+    args: z8.array(z8.string({ description: "Command arguments" })).optional(),
+    outputFile: filePathSchema("Output path"),
+    outputTransform: outputTransformSchema.optional()
+  },
+  {
+    description: "How to execute runner"
+  }
+);
+var onProgressSchema = z8.function().args(z8.unknown()).returns(z8.void());
+var runnerFunctionSchema = z8.function().args(onProgressSchema.optional()).returns(z8.union([auditOutputsSchema, z8.promise(auditOutputsSchema)]));
+
+// packages/models/src/lib/plugin-config.ts
+var pluginMetaSchema = packageVersionSchema({
+  optional: true
+}).merge(
+  metaSchema({
+    titleDescription: "Descriptive name",
+    descriptionDescription: "Description (markdown)",
+    docsUrlDescription: "Plugin documentation site",
+    description: "Plugin metadata"
+  })
+).merge(
+  z9.object({
+    slug: slugSchema("References plugin. ID (unique within core config)"),
+    icon: materialIconSchema
+  })
+);
+var pluginDataSchema = z9.object({
+  runner: z9.union([runnerConfigSchema, runnerFunctionSchema]),
+  audits: pluginAuditsSchema,
+  groups: auditGroupsSchema
+});
+var pluginConfigSchema = pluginMetaSchema.merge(pluginDataSchema).refine(
+  (pluginCfg) => !getMissingRefsFromGroups(pluginCfg),
+  (pluginCfg) => ({
+    message: missingRefsFromGroupsErrorMsg(pluginCfg)
+  })
+);
+function missingRefsFromGroupsErrorMsg(pluginCfg) {
+  const missingRefs = getMissingRefsFromGroups(pluginCfg);
+  return `In the groups, the following audit ref's needs to point to a audit in this plugin config: ${errorItems(
+    missingRefs
+  )}`;
+}
+function getMissingRefsFromGroups(pluginCfg) {
+  if (pluginCfg?.groups?.length && pluginCfg?.audits?.length) {
+    const groups = pluginCfg?.groups || [];
+    const audits = pluginCfg?.audits || [];
+    return hasMissingStrings(
+      groups.flatMap(({ refs: audits2 }) => audits2.map(({ slug: ref }) => ref)),
+      audits.map(({ slug }) => slug)
+    );
+  }
+  return false;
+}
+
+// packages/models/src/lib/upload-config.ts
+import { z as z10 } from "zod";
+var uploadConfigSchema = z10.object({
+  server: urlSchema("URL of deployed portal API"),
+  apiKey: z10.string({
+    description: "API key with write access to portal (use `process.env` for security)"
+  }),
+  organization: z10.string({
+    description: "Organization in code versioning system"
+  }),
+  project: z10.string({
+    description: "Project in code versioning system"
+  })
+});
+
+// packages/models/src/lib/core-config.ts
+var unrefinedCoreConfigSchema = z11.object({
+  plugins: z11.array(pluginConfigSchema, {
+    description: "List of plugins to be used (official, community-provided, or custom)"
+  }),
+  /** portal configuration for persisting results */
+  persist: persistConfigSchema,
+  /** portal configuration for uploading results */
+  upload: uploadConfigSchema.optional(),
+  categories: z11.array(categoryConfigSchema, {
+    description: "Categorization of individual audits"
+  }).refine(
+    (categoryCfg) => !getDuplicateSlugCategories(categoryCfg),
+    (categoryCfg) => ({
+      message: duplicateSlugCategoriesErrorMsg(categoryCfg)
+    })
+  )
+});
+var coreConfigSchema = refineCoreConfig(unrefinedCoreConfigSchema);
+function refineCoreConfig(schema) {
+  return schema.refine(
+    (coreCfg) => !getMissingRefsForCategories(coreCfg),
+    (coreCfg) => ({
+      message: missingRefsForCategoriesErrorMsg(coreCfg)
+    })
+  );
+}
+function missingRefsForCategoriesErrorMsg(coreCfg) {
+  const missingRefs = getMissingRefsForCategories(coreCfg);
+  return `In the categories, the following plugin refs do not exist in the provided plugins: ${errorItems(
+    missingRefs
+  )}`;
+}
+function getMissingRefsForCategories(coreCfg) {
+  const missingRefs = [];
+  const auditRefsFromCategory = coreCfg.categories.flatMap(
+    ({ refs }) => refs.filter(({ type }) => type === "audit").map(({ plugin, slug }) => `${plugin}/${slug}`)
+  );
+  const auditRefsFromPlugins = coreCfg.plugins.flatMap(
+    ({ audits, slug: pluginSlug }) => {
+      return audits.map(({ slug }) => `${pluginSlug}/${slug}`);
+    }
+  );
+  const missingAuditRefs = hasMissingStrings(
+    auditRefsFromCategory,
+    auditRefsFromPlugins
+  );
+  if (Array.isArray(missingAuditRefs) && missingAuditRefs.length > 0) {
+    missingRefs.push(...missingAuditRefs);
+  }
+  const groupRefsFromCategory = coreCfg.categories.flatMap(
+    ({ refs }) => refs.filter(({ type }) => type === "group").map(({ plugin, slug }) => `${plugin}#${slug} (group)`)
+  );
+  const groupRefsFromPlugins = coreCfg.plugins.flatMap(
+    ({ groups, slug: pluginSlug }) => {
+      return Array.isArray(groups) ? groups.map(({ slug }) => `${pluginSlug}#${slug} (group)`) : [];
+    }
+  );
+  const missingGroupRefs = hasMissingStrings(
+    groupRefsFromCategory,
+    groupRefsFromPlugins
+  );
+  if (Array.isArray(missingGroupRefs) && missingGroupRefs.length > 0) {
+    missingRefs.push(...missingGroupRefs);
+  }
+  return missingRefs.length ? missingRefs : false;
+}
+function duplicateSlugCategoriesErrorMsg(categories) {
+  const duplicateStringSlugs = getDuplicateSlugCategories(categories);
+  return `In the categories, the following slugs are duplicated: ${errorItems(
+    duplicateStringSlugs
+  )}`;
+}
+function getDuplicateSlugCategories(categories) {
+  return hasDuplicateStrings(categories.map(({ slug }) => slug));
+}
+
+// packages/models/src/lib/report.ts
+import { z as z12 } from "zod";
+var auditReportSchema = auditSchema.merge(auditOutputSchema);
+var pluginReportSchema = pluginMetaSchema.merge(
+  executionMetaSchema({
+    descriptionDate: "Start date and time of plugin run",
+    descriptionDuration: "Duration of the plugin run in ms"
+  })
+).merge(
+  z12.object({
+    audits: z12.array(auditReportSchema),
+    groups: z12.array(auditGroupSchema).optional()
+  })
+);
+var reportSchema = packageVersionSchema({
+  versionDescription: "NPM version of the CLI"
+}).merge(
+  executionMetaSchema({
+    descriptionDate: "Start date and time of the collect run",
+    descriptionDuration: "Duration of the collect run in ms"
+  })
+).merge(
+  z12.object(
+    {
+      categories: z12.array(categoryConfigSchema),
+      plugins: z12.array(pluginReportSchema)
+    },
+    { description: "Collect output data" }
+  )
+);
+export {
+  auditGroupSchema,
+  auditOutputsSchema,
+  auditReportSchema,
+  auditSchema,
+  categoryConfigSchema,
+  coreConfigSchema,
+  formatSchema,
+  materialIconSchema,
+  onProgressSchema,
+  persistConfigSchema,
+  pluginAuditsSchema,
+  pluginConfigSchema,
+  pluginReportSchema,
+  refineCoreConfig,
+  reportSchema,
+  runnerConfigSchema,
+  unrefinedCoreConfigSchema,
+  uploadConfigSchema
+};

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@code-pushup/models",
+  "version": "0.1.0",
+  "dependencies": {
+    "zod": "^3.22.1",
+    "@code-pushup/portal-client": "^0.1.2"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts"
+}

package/src/index.d.ts

@@ -0,0 +1,12 @@
+export { CategoryConfig, CategoryRef, categoryConfigSchema, } from './lib/category-config';
+export { CoreConfig, coreConfigSchema, refineCoreConfig, unrefinedCoreConfigSchema, } from './lib/core-config';
+export { Format, PersistConfig, formatSchema, persistConfigSchema, } from './lib/persist-config';
+export { PluginConfig, pluginConfigSchema } from './lib/plugin-config';
+export { auditSchema, Audit, pluginAuditsSchema, } from './lib/plugin-config-audits';
+export { AuditGroupRef, AuditGroup, auditGroupSchema, } from './lib/plugin-config-groups';
+export { AuditOutput, AuditOutputs, auditOutputsSchema, } from './lib/plugin-process-output';
+export { Issue, IssueSeverity } from './lib/plugin-process-output-audit-issue';
+export { AuditReport, auditReportSchema, PluginReport, Report, pluginReportSchema, reportSchema, } from './lib/report';
+export { UploadConfig, uploadConfigSchema } from './lib/upload-config';
+export { materialIconSchema } from './lib/implementation/schemas';
+export { onProgressSchema, OnProgress, RunnerFunction, runnerConfigSchema, RunnerConfig, } from './lib/plugin-config-runner';