docs(cli): add docs for custom plugins (#312)

examples/plugins/code-pushup.config.ts

@@ -1,7 +1,6 @@
-import {
-  create as fileSizePlugin,
+import fileSizePlugin, {
   recommendedRefs as fileSizeRecommendedRefs,
-} from './src/file-size/file-size.plugin';
+} from './src/file-size/src/file-size.plugin';
 
 /**
  * Run it with:

examples/plugins/src/file-size/README.md

@@ -0,0 +1,69 @@
+# file-size-plugin
+
+🕵️ **Code PushUp plugin for detecting changes in file size using different compressions** 📋
+
+---
+
+The plugin crawls the file base depending on your configuration and reports about their file size.
+
+You can configure the plugin with the following options:
+
+- directory to crawl
+- file name pattern
+- budget as number in bytes
+
+## Getting started
+
+1. If you haven't already, install [@code-pushup/cli](../cli/README.md) and create a configuration file.
+
+2. Copy the [plugin source](../file-size) as is into your project
+
+3. Add this plugin to the `plugins` array in your Code PushUp CLI config file (e.g. `code-pushup.config.js`).
+
+   Pass in the path on the directory to crawl (relative to `process.cwd()`), as well as patterns and a budget.
+
+   ```js
+   import fileSizePlugin from './file-size.plugin';
+
+   export default {
+     // ...
+     plugins: [
+       // ...
+       fileSizePlugin({
+         directory: 'dist',
+         patterns: /.js$/,
+         budget: 42000,
+       }),
+     ],
+   };
+   ```
+
+4. (Optional) Reference audits (or groups) that you wish to include in custom categories (use `npx code-pushup print-config` to list audits and groups).
+
+   Assign weights based on what influence each audit and group should have on the overall category score (assign weight 0 to only include it for extra info, without influencing the category score).
+
+   ```js
+   import fileSizePlugin, { recommendedRefs as fileSizeRecommendedRefs } from './file-size.plugin';
+
+   export default {
+     // ...
+     categories: [
+       // ...
+       {
+         slug: 'performance',
+         title: 'Performance',
+         refs: [...fileSizeRecommendedRefs],
+       },
+     ],
+   };
+   ```
+
+5. Run the CLI with `npx code-pushup collect` and view or upload report (refer to [CLI docs](../cli/README.md)).
+
+## Audits
+
+Detailed information about the audits can be found in the docs folder of the plugin.
+
+The following audits are present:
+
+- [file-size-unmodified](@TODO - link to docs/file-size-unmodified.audit.md)

examples/plugins/src/file-size/docs/file-size-unmodified.audit.md

@@ -0,0 +1,58 @@
+# File Size Audit - Unmodified
+
+🕵️ **An audit to check JavaScript file size in a directory. The files are not modified and takes as they are.** 📏
+
+---
+
+The audit evaluates the size of a file by using the `stat` function for the `fs:promises` node package.
+
+You can configure the plugin with the following options:
+
+- `budget` as number in bytes
+
+## Details
+
+The audit provides details in cases a file result is given.
+
+### Issues
+
+**Audit passed**
+A `Issue` with severity `info` is present and names to the given file.
+
+```md
+  <table>
+    <tr>
+      <th>Severity</th>
+      <th>Message</th>
+      <th>Source file</th>
+      <th>Line(s)</th>
+    </tr>
+    <tr>
+      <td>ℹ️ <i>info</i></td>
+      <td>File file.js OK</td>
+      <td><code>src/file.js</code></td>
+      <td></td>
+    </tr>
+  </table>
+```
+
+**Audit failed**
+A `Issue` with severity `error` is present and names to the given file.  
+The file sizes of the given file, the budget as well as the size difference is mentioned in the message.
+
+```md
+  <table>
+    <tr>
+      <th>Severity</th>
+      <th>Message</th>
+      <th>Source file</th>
+      <th>Line(s)</th>
+    </tr>
+    <tr>
+       <td>🚨 <i>error</i></td>
+      <td>File file.js is 17.31 kB bytes too big. (budget: 41.02 kB)</td>
+      <td><code>src/file.js</code></td>
+      <td></td>
+    </tr>
+  </table>
+```

examples/plugins/src/file-size/file-size.plugin.ts → examples/plugins/src/file-size/src/file-size.plugin.ts

@@ -13,7 +13,7 @@ import {
   formatBytes,
   pluralizeToken,
   toUnixPath,
-} from '../../../../dist/packages/utils';
+} from '../../../../../dist/packages/utils';
 
 export type PluginOptions = {
   directory: string;
@@ -25,12 +25,13 @@ type RunnerOptions = PluginOptions;
 
 export const pluginSlug = 'file-size';
 
-const fileSizeAuditSlug = 'file-size-check';
+const fileSizeAuditSlug = 'file-size-unmodified';
 export const auditsMap = {
   [fileSizeAuditSlug]: {
     slug: fileSizeAuditSlug,
-    title: 'File Size Audit',
-    description: 'An audit to check JavaScript file size in a directory.',
+    title: 'File Size Audit - Unmodified',
+    description:
+      'An audit to check JavaScript file size in a directory. The files are not modified and takes as they are.',
   },
 };
 export const audits = Object.values(auditsMap);
@@ -125,7 +126,7 @@ export function displayValue(numberOfFiles: number): string {
   return `${pluralizeToken('file', numberOfFiles)} oversize`;
 }
 
-export async function fileSizeIssues(options: {
+export function fileSizeIssues(options: {
   directory: string;
   pattern?: string | RegExp;
   budget?: number;
@@ -192,3 +193,5 @@ export function assertFileSize(
     message: infoMessage(file, formattedSize),
   } satisfies Issue;
 }
+
+export default create;

examples/plugins/src/file-size/file-size.plugin.unit.test.ts → examples/plugins/src/file-size/src/file-size.plugin.unit.test.ts

@@ -198,7 +198,7 @@ describe('runnerFunction', () => {
   const filesizeAuditOutputBase = {
     displayValue: '0 files oversize',
     score: 1,
-    slug: 'file-size-check',
+    slug: 'file-size-unmodified',
     value: 0,
   };
 

examples/plugins/src/index.ts

@@ -3,4 +3,4 @@ export {
   create as fileSizePlugin,
   recommendedRefs as fileSizeRecommendedRefs,
   PluginOptions as FileSizePluginOptions,
-} from './file-size/file-size.plugin';
+} from './file-size/src/file-size.plugin';

packages/cli/README.md

@@ -128,6 +128,17 @@ jobs:
       - run: npx code-pushup autorun --upload.apiKey=${{ secrets.PORTAL_API_KEY }}
 ```
 
+## Custom Plugins
+
+We provide comprehensive documentation on [how to create a custom plugin](./docs/custom-plugins.md).
+
+The repository also maintains a set of plugin examples showcasing different scenarios.  
+Each example is fully tested to give demonstrate best practices for plugin testing.
+
+**Example for custom plugins:**
+
+- [File Size](../../examples/plugins/src/file-size)
+
 ## CLI commands and options
 
 ### Global Options