refactor: make categories optional in core config (#437)

Closes #407 

I aimed for handling the optional categories only in the cli layer and
maintained the existing data structure fully in reports. I just hide the
sections for empty categories.

Follow-up by @Tlacenka:
- I added tests for scoring and sorting reports.
- I allowed passing both `undefined` and `[]` by configuring categories
schema to allow empty array.
- I reduced minimal mocks.
- I typed categories as a non-optional property as soon as in the only
plugins middleware.

---------

Co-authored-by: Katerina Pilatova <katerina.pilatova@flowup.cz>

Author: BioPhoton

packages/cli/README.md

@@ -43,9 +43,6 @@ _If you're looking for programmatic usage, then refer to the underlying [@code-p
      plugins: [
        // ...
      ],
-     categories: [
-       // ...
-     ],
    };
    ```
 
@@ -67,7 +64,7 @@ _If you're looking for programmatic usage, then refer to the underlying [@code-p
    };
    ```
 
-4. Define your custom categories.
+4. Optionally define your custom categories. This section provides an overview of thematically related audits and groups.
 
    ```js
    export default {
@@ -77,6 +74,7 @@ _If you're looking for programmatic usage, then refer to the underlying [@code-p
          slug: 'performance',
          title: 'Performance',
          refs: [
+           // reference to an existing audit or group from plugins
            {
              type: 'audit',
              plugin: 'eslint',

packages/cli/docs/custom-plugins.md

@@ -97,18 +97,12 @@ Code PushUp Report - @code-pushup/core@x.y.z
 My plugin audits
 ● My audit                                                            0
 
-Categories
-┌──────────┬───────┬────────┐
-│ Category │ Score │ Audits │
-└──────────┴───────┴────────┘
-
 Made with ❤ by code-pushup.dev
 ```
 
 </details>
 
-The categories are empty for now. But under the audit listing you can see your plugin title `My plugin`, its listed
-audit `My audit` and the resulting value `0`.
+Under the audit listing you can see your plugin title `My plugin`, its listed audit `My audit` and the resulting value `0`.
 
 ## Plugin output
 
@@ -251,11 +245,6 @@ Code PushUp Report - @code-pushup/core@x.y.z
 File size plugin audits
 ● File size audit                                                            2 files
 
-Categories
-┌──────────┬───────┬────────┐
-│ Category │ Score │ Audits │
-└──────────┴───────┴────────┘
-
 Made with ❤ by code-pushup.dev
 ```
 
@@ -387,11 +376,6 @@ Code PushUp Report - @code-pushup/core@x.y.z
 Chrome Lighthosue audits
 ● Largest Contentful Paint                                                0
 
-Categories
-┌──────────┬───────┬────────┐
-│ Category │ Score │ Audits │
-└──────────┴───────┴────────┘
-
 Made with ❤ by code-pushup.dev
 ```
 
@@ -498,37 +482,6 @@ async function runnerFunction(options: Options): Promise<AuditOutputs> {
 }
 ```
 
-### Audit groups
-
-As an optional property a plugin can maintain `groups` as an array of [`Group`s](@TODO).
-While [categories](#plugins-and-categories) can score audits across plugins, groups are only targeting plugins within a plugin.
-For simple plugins this is not needed but it is beneficial in bigger plugins as audit groups also simplify the configuration.
-
-An audit group maintains:
-
-- metadata about the group [GroupMeta](@TODO)
-- a list of referenced audits under `refs` as [GroupRef](@TODO) array
-
-The minimum information of an audit group looks like this:
-
-```typescript
-import { Group } from '@code-pushup/models';
-
-const myGroup: Group = {
-  slug: 'performance',
-  refs: [
-    {
-      slug: 'file-size-audit',
-      weight: 1,
-    },
-  ],
-  // optional details
-};
-```
-
-The weight property of a reference is used to calculate a score for all audits listed under refs.  
-A weight of 0 can be used for informative audits and a value from 1 upward to give a weight in the score compared to other audits.
-
 ### Audit details
 
 To have better attribution in your audits you can use the `details` section in `AuditOutputs`.
@@ -630,11 +583,42 @@ The `report.md` file should contain a similar content like the following:
 
 </details>
 
-## Plugins and categories
+## Groups
+
+As an optional property a plugin can maintain `groups` as an array of [`Group`s](@TODO).
+While [categories](#plugins-and-categories) can score audits across plugins, groups are only targeting audits within a plugin.
+For simple plugins this is not needed but it is beneficial in bigger plugins as audit groups also simplify the configuration.
+
+An audit group maintains:
+
+- metadata about the group [GroupMeta](@TODO)
+- a list of referenced audits under `refs` as [GroupRef](@TODO) array
+
+The minimum information of an audit group looks like this:
+
+```typescript
+import { Group } from '@code-pushup/models';
+
+const myGroup: Group = {
+  slug: 'performance',
+  refs: [
+    {
+      slug: 'file-size-audit',
+      weight: 1,
+    },
+  ],
+  // optional details
+};
+```
+
+The weight property of a reference is used to calculate a score for all audits listed under refs.  
+A weight of 0 can be used for informative audits and a value from 1 upward to give a weight in the score compared to other audits.
+
+## Categories
 
 In this chapter we will see how plugin results contribute to the category scoring.
 
-**basic categories setup**
+**basic category setup**
 In this example we create a Performance category which contains one audit and one group.
 
 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).

packages/cli/src/lib/autorun/autorun-command.ts

@@ -35,6 +35,14 @@ export function yargsAutorunCommandObject() {
 
       await collectAndPersistReports(optionsWithFormat);
 
+      if (options.categories.length === 0) {
+        console.info(
+          chalk.gray(
+            '💡 Configure categories to see the scores in an overview table. See: https://github.com/code-pushup/cli/blob/main/packages/cli/README.md',
+          ),
+        );
+      }
+
       if (options.upload) {
         await upload(options);
       } else {

packages/cli/src/lib/collect/collect-command.ts

@@ -18,6 +18,15 @@ export function yargsCollectCommandObject(): CommandModule {
       console.info(chalk.bold(CLI_NAME));
       console.info(chalk.gray(`Run ${command}...`));
       await collectAndPersistReports(options);
+
+      if (options.categories.length === 0) {
+        console.info(
+          chalk.gray(
+            '💡 Configure categories to see the scores in an overview table. See: https://github.com/code-pushup/cli/blob/main/packages/cli/README.md',
+          ),
+        );
+      }
+
       const { upload = {} } = args as unknown as Record<
         'upload',
         object | undefined

packages/cli/src/lib/implementation/core-config.integration.test.ts

@@ -23,22 +23,23 @@ vi.mock('@code-pushup/core', async () => {
           outputDir: 'rc-outputDir',
         },
       };
-
       const persistOnlyFilename = {
         ...CORE_CONFIG_MOCK,
         persist: {
           filename: 'rc-filename',
         },
       };
-
-      const noPersistFilename = CORE_CONFIG_MOCK;
+      const noPersist = CORE_CONFIG_MOCK;
+      const noCategory = { plugins: CORE_CONFIG_MOCK.plugins };
 
       return filepath.includes('all-persist-options')
         ? allPersistOptions
-        : filepath.includes('no-persist')
-        ? noPersistFilename
         : filepath.includes('persist-only-filename')
         ? persistOnlyFilename
+        : filepath.includes('no-persist')
+        ? noPersist
+        : filepath.includes('no-category')
+        ? noCategory
         : CORE_CONFIG_MOCK;
     }),
   };
@@ -137,4 +138,16 @@ describe('parsing values from CLI and middleware', () => {
       outputDir: 'cli-outputdir',
     });
   });
+
+  it('should set empty array for categories if not given in config file', async () => {
+    const { categories } = await yargsCli<CoreConfig>(
+      ['--config=./no-category.config.ts'],
+      {
+        options: { ...yargsCoreConfigOptionsDefinition() },
+        middlewares: [{ middlewareFunction: coreConfigMiddleware }],
+      },
+    ).parseAsync();
+
+    expect(categories).toEqual([]);
+  });
 });

packages/cli/src/lib/implementation/core-config.middleware.ts

@@ -22,6 +22,7 @@ export async function coreConfigMiddleware<
   const {
     persist: rcPersist,
     upload: rcUpload,
+    categories: rcCategories,
     ...remainingRcConfig
   } = importedRc;
 
@@ -39,6 +40,7 @@ export async function coreConfigMiddleware<
       format: cliPersist?.format ?? rcPersist?.format ?? PERSIST_FORMAT,
       filename: cliPersist?.filename ?? rcPersist?.filename ?? PERSIST_FILENAME,
     },
+    categories: rcCategories ?? [],
   };
 
   return parsedProcessArgs;

packages/cli/src/lib/implementation/only-plugins.middleware.ts

@@ -17,12 +17,13 @@ export function onlyPluginsMiddleware<
 
   validateOnlyPluginsOption(cliOptions.plugins, cliOptions);
 
-  const parsedProcessArgs: CoreConfig & GeneralCliOptions & OnlyPluginsOptions =
-    {
-      ...cliOptions,
-      plugins: filterPluginsBySlug(cliOptions.plugins, cliOptions),
-      categories: filterCategoryByPluginSlug(cliOptions.categories, cliOptions),
-    };
+  const parsedProcessArgs: Required<CoreConfig> &
+    GeneralCliOptions &
+    OnlyPluginsOptions = {
+    ...cliOptions,
+    plugins: filterPluginsBySlug(cliOptions.plugins, cliOptions),
+    categories: filterCategoryByPluginSlug(cliOptions.categories, cliOptions),
+  };
 
   return parsedProcessArgs;
 }

packages/cli/src/lib/implementation/only-plugins.utils.ts

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { CoreConfig } from '@code-pushup/models';
+import { CategoryConfig, CoreConfig } from '@code-pushup/models';
 
 export function filterPluginsBySlug(
   plugins: CoreConfig['plugins'],
@@ -14,12 +14,15 @@ export function filterPluginsBySlug(
 // skip the whole category if it has at least one skipped plugin ref
 // see https://github.com/code-pushup/cli/pull/246#discussion_r1392274281
 export function filterCategoryByPluginSlug(
-  categories: CoreConfig['categories'],
+  categories: CategoryConfig[],
   {
     onlyPlugins,
     verbose = false,
   }: { onlyPlugins?: string[]; verbose?: boolean },
-): CoreConfig['categories'] {
+): CategoryConfig[] {
+  if (categories.length === 0) {
+    return categories;
+  }
   if (!onlyPlugins?.length) {
     return categories;
   }

packages/cli/src/lib/implementation/only-plugins.utils.unit.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect } from 'vitest';
-import { CoreConfig } from '@code-pushup/models';
+import { CategoryConfig, CoreConfig } from '@code-pushup/models';
 import {
   filterCategoryByPluginSlug,
   filterPluginsBySlug,
@@ -41,7 +41,7 @@ describe('filterCategoryByPluginSlug', () => {
         [
           { refs: [{ slug: 'plugin1' }, { slug: 'plugin2' }] },
           { refs: [{ slug: 'plugin3' }] },
-        ] as CoreConfig['categories'],
+        ] as CategoryConfig[],
         {},
       ),
     ).toEqual([
@@ -56,7 +56,7 @@ describe('filterCategoryByPluginSlug', () => {
         [
           { refs: [{ slug: 'plugin1' }, { slug: 'plugin2' }] },
           { refs: [{ slug: 'plugin3' }] },
-        ] as CoreConfig['categories'],
+        ] as CategoryConfig[],
         { onlyPlugins: ['plugin1', 'plugin3'] },
       ),
     ).toEqual([{ refs: [{ slug: 'plugin3' }] }]);
@@ -70,7 +70,7 @@ describe('filterCategoryByPluginSlug', () => {
           refs: [{ slug: 'plugin1' }, { slug: 'plugin2' }, { slug: 'plugin4' }],
         },
         { title: 'category2', refs: [{ slug: 'plugin3' }] },
-      ] as CoreConfig['categories'],
+      ] as CategoryConfig[],
       {
         onlyPlugins: ['plugin1', 'plugin3'],
         verbose: true,

packages/core/src/lib/collect-and-persist.ts

@@ -5,9 +5,8 @@ import { logPersistedResults, persistReport } from './implementation/persist';
 import { normalizePersistConfig } from './normalize';
 import { GlobalOptions } from './types';
 
-export type CollectAndPersistReportsOptions = Pick<
-  CoreConfig,
-  'persist' | 'plugins' | 'categories'
+export type CollectAndPersistReportsOptions = Required<
+  Pick<CoreConfig, 'persist' | 'plugins' | 'categories'>
 > &
   GlobalOptions;