docs(examples-plugins): add example plugin file-size (#315)

Author: BioPhoton

code-pushup.config.ts

@@ -2,8 +2,13 @@ import nx from '@nx/devkit';
 import 'dotenv/config';
 import type { ESLint } from 'eslint';
 import { stat } from 'node:fs/promises';
+import { join } from 'path';
 import { z } from 'zod';
 import eslintPlugin from './dist/packages/plugin-eslint';
+import {
+  fileSizePlugin,
+  fileSizeRecommendedRefs,
+} from './examples/plugins/src';
 import type { CoreConfig } from './packages/models/src';
 
 const exists = (path: string) =>
@@ -58,7 +63,14 @@ const config: CoreConfig = {
     project: env.CP_PROJECT,
   },
 
-  plugins: [await eslintPlugin({ eslintrc: eslintConfig, patterns })],
+  plugins: [
+    await eslintPlugin({ eslintrc: eslintConfig, patterns }),
+    await fileSizePlugin({
+      directory: './dist/packages',
+      pattern: /\.js$/,
+      budget: 42000,
+    }),
+  ],
 
   categories: [
     {
@@ -73,6 +85,11 @@ const config: CoreConfig = {
         { type: 'group', plugin: 'eslint', slug: 'suggestions', weight: 1 },
       ],
     },
+    {
+      slug: 'performance',
+      title: 'Performance',
+      refs: [...fileSizeRecommendedRefs],
+    },
   ],
 };
 

examples/plugins/.eslintrc.json

@@ -0,0 +1,39 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {
+        "@nx/enforce-module-boundaries": ["off"]
+      }
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "parserOptions": {
+        "project": ["examples/plugins/tsconfig.*?.json"]
+      },
+      "rules": {}
+    },
+    {
+      "files": ["*.test.ts", "*.test.tsx"],
+      "parserOptions": {
+        "project": ["examples/plugins/tsconfig.*?.json"]
+      },
+      "rules": {
+        "max-lines": "off"
+      }
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": ["error"]
+      }
+    }
+  ]
+}

examples/plugins/code-pushup.config.ts

@@ -0,0 +1,38 @@
+import {
+  create as fileSizePlugin,
+  recommendedRefs as fileSizeRecommendedRefs,
+} from './src/file-size/file-size.plugin';
+
+/**
+ * Run it with:
+ * `nx run-collect examples-plugins`
+ *
+ * - For all formats use `--persist.format=md,json`
+ * - For better debugging use `--verbose --no-progress`
+ *
+ */
+
+const outputDir = '.code-pushup';
+// eslint-disable-next-line unicorn/no-unreadable-iife
+const config = (() => ({
+  persist: {
+    outputDir,
+  },
+  plugins: [
+    fileSizePlugin({
+      directory: './dist',
+      pattern: /\.js$/,
+      // eslint-disable-next-line no-magic-numbers
+      budget: 42_000,
+    }),
+  ],
+  categories: [
+    {
+      slug: 'performance',
+      title: 'Performance',
+      refs: [...fileSizeRecommendedRefs],
+    },
+  ],
+}))();
+
+export default config;

examples/plugins/project.json

@@ -0,0 +1,40 @@
+{
+  "name": "examples-plugins",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "examples/plugins/src",
+  "projectType": "library",
+  "implicitDependencies": ["cli"],
+  "targets": {
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": ["examples/plugins/**/*.ts"]
+      },
+      "dependsOn": ["^build"]
+    },
+    "unit-test": {
+      "executor": "@nx/vite:test",
+      "outputs": ["{options.reportsDirectory}"],
+      "options": {
+        "config": "examples/plugins/vite.config.unit.ts",
+        "reportsDirectory": "../../coverage/examples-plugins/unit-tests"
+      },
+      "dependsOn": ["^build"]
+    },
+    "integration-test": {
+      "executor": "@nx/vite:test",
+      "outputs": ["{options.reportsDirectory}"],
+      "options": {
+        "config": "examples/plugins/vite.config.integration.ts",
+        "reportsDirectory": "../../coverage/examples-plugins/integration-tests"
+      },
+      "dependsOn": ["^build"]
+    },
+    "run-collect": {
+      "command": "npx dist/packages/cli collect --config=examples/plugins/code-pushup.config.ts --persist.format=md",
+      "dependsOn": ["^build"]
+    }
+  },
+  "tags": []
+}

examples/plugins/src/file-size/file-size.plugin.integration.test.ts

@@ -0,0 +1,115 @@
+import { vol } from 'memfs';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { executePlugin } from '@code-pushup/core';
+import {
+  auditSchema,
+  categoryRefSchema,
+  pluginConfigSchema,
+} from '@code-pushup/models';
+import { MEMFS_VOLUME } from '@code-pushup/testing-utils';
+import {
+  PluginOptions,
+  audits,
+  create,
+  recommendedRefs,
+  pluginSlug as slug,
+} from './file-size.plugin';
+
+const projectJson = JSON.stringify(
+  {
+    test: 42,
+    arr: [1, 2, 3],
+    obj: {
+      test: 42,
+    },
+  },
+  null,
+  2,
+);
+const testJs = `
+    const str = 'Hello World'
+    const num = 42;
+    const obj = ${projectJson};
+  `;
+
+describe('create', () => {
+  const baseOptions: PluginOptions = {
+    directory: '/',
+  };
+
+  beforeEach(() => {
+    vol.fromJSON(
+      {
+        'project.json': projectJson,
+        'src/test.js': testJs,
+      },
+      MEMFS_VOLUME,
+    );
+  });
+
+  it('should return valid PluginConfig', () => {
+    const pluginConfig = create(baseOptions);
+    expect(() => pluginConfigSchema.parse(pluginConfig)).not.toThrow();
+    expect(pluginConfig).toEqual({
+      audits,
+      description:
+        'A plugin to measure and assert filesize of files in a directory.',
+      icon: 'javascript',
+      runner: expect.any(Function),
+      slug,
+      title: 'File Size',
+    });
+  });
+
+  it('should return PluginConfig that executes correctly', async () => {
+    const pluginConfig = create(baseOptions);
+    await expect(executePlugin(pluginConfig)).resolves.toMatchObject({
+      description:
+        'A plugin to measure and assert filesize of files in a directory.',
+      slug,
+      title: 'File Size',
+      duration: expect.any(Number),
+      date: expect.any(String),
+      audits: expect.any(Array),
+    });
+  });
+
+  it('should use pattern', async () => {
+    const pluginConfig = create({
+      ...baseOptions,
+      pattern: /\.js$/,
+    });
+    const { audits: auditOutputs } = await executePlugin(pluginConfig);
+
+    expect(auditOutputs).toHaveLength(1);
+    expect(auditOutputs[0]?.score).toBe(1);
+    expect(auditOutputs[0]?.details?.issues).toHaveLength(1);
+  });
+
+  it('should use budget', async () => {
+    const pluginConfig = create({
+      ...baseOptions,
+      budget: 0,
+    });
+    const { audits: auditOutputs } = await executePlugin(pluginConfig);
+
+    expect(auditOutputs).toHaveLength(1);
+    expect(auditOutputs[0]?.score).toBe(0);
+    expect(auditOutputs[0]?.details?.issues).toHaveLength(2);
+  });
+});
+
+describe('audits', () => {
+  it.each(audits)('should be a valid audit meta info', audit => {
+    expect(() => auditSchema.parse(audit)).not.toThrow();
+  });
+});
+
+describe('recommendedRefs', () => {
+  it.each(recommendedRefs)(
+    'should be a valid category reference',
+    categoryRef => {
+      expect(() => categoryRefSchema.parse(categoryRef)).not.toThrow();
+    },
+  );
+});