@code-pushup/cli 0.12.1 → 0.12.3

package/README.md

@@ -23,6 +23,8 @@ _If you're looking for programmatic usage, then refer to the underlying [@code-p
 ## Getting started
 
 1. Install as a dev dependency with your package manager:
+   <details>
+   <summary>Installation command for <code>npm</code>, <code>yarn</code> and <code>pnpm</code></summary>
 
    ```sh
    npm install --save-dev @code-pushup/cli
@@ -36,6 +38,8 @@ _If you're looking for programmatic usage, then refer to the underlying [@code-p
    pnpm add --save-dev @code-pushup/cli
    ```
 
+   </details>
+
 2. Create a `code-pushup.config.js` configuration file (`.ts` or `.mjs` extensions are also supported).
 
    ```js
@@ -43,9 +47,6 @@ _If you're looking for programmatic usage, then refer to the underlying [@code-p
      plugins: [
        // ...
      ],
-     categories: [
-       // ...
-     ],
    };
    ```
 
@@ -67,7 +68,13 @@ _If you're looking for programmatic usage, then refer to the underlying [@code-p
    };
    ```
 
-4. Define your custom categories.
+4. Run the CLI with `npx code-pushup` (see `--help` for list of commands and arguments).
+
+5. View report file(s) in output directory (specified by `persist.outputDir` configuration).
+
+### Set up categories (optional)
+
+1. Define your custom categories.
 
    ```js
    export default {
@@ -77,6 +84,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',
@@ -91,9 +99,9 @@ _If you're looking for programmatic usage, then refer to the underlying [@code-p
    };
    ```
 
-5. Run the CLI with `npx code-pushup` (see `--help` for list of commands and arguments).
+2. Run the CLI with `npx code-pushup`.
 
-6. View report file(s) in output directory (specified by `persist.outputDir` configuration).
+3. View report file(s) including category section in output directory.
 
 ## Portal integration
 
@@ -172,13 +180,15 @@ Each example is fully tested to demonstrate best practices for plugin testing as
 > All common options, except `--onlyPlugins`, can be specified in the configuration file as well.
 > CLI arguments take precedence over configuration file options.
 
-> [!NOTE]
+> [!NOTE]  
 > The `--upload.*` group of options is applicable to all commands except `collect`.
 
 ### Commands
 
 #### `collect` command
 
+<img src="./docs/images/cli-run-stdout-example.png" width="400" alt="example of code-pushup terminal output">
+
 Usage:
 `code-pushup collect [options]`
 

package/index.js

@@ -40,6 +40,9 @@ function exists(value) {
   return value != null;
 }
 function getMissingRefsForCategories(categories, plugins) {
+  if (categories.length === 0) {
+    return false;
+  }
   const auditRefsFromCategory = categories.flatMap(
     ({ refs }) => refs.filter(({ type }) => type === "audit").map(({ plugin, slug }) => `${plugin}/${slug}`)
   );
@@ -314,7 +317,7 @@ function getDuplicateRefsInCategoryMetrics(metrics) {
 }
 var categoriesSchema = z5.array(categoryConfigSchema, {
   description: "Categorization of individual audits"
-}).min(1).refine(
+}).refine(
   (categoryCfg) => !getDuplicateSlugCategories(categoryCfg),
   (categoryCfg) => ({
     message: duplicateSlugCategoriesErrorMsg(categoryCfg)
@@ -472,15 +475,15 @@ var unrefinedCoreConfigSchema = z11.object({
   persist: persistConfigSchema.optional(),
   /** portal configuration for uploading results */
   upload: uploadConfigSchema.optional(),
-  categories: categoriesSchema
+  categories: categoriesSchema.optional()
 });
 var coreConfigSchema = refineCoreConfig(unrefinedCoreConfigSchema);
 function refineCoreConfig(schema) {
   return schema.refine(
-    (coreCfg) => !getMissingRefsForCategories(coreCfg.categories, coreCfg.plugins),
+    (coreCfg) => !getMissingRefsForCategories(coreCfg.categories ?? [], coreCfg.plugins),
     (coreCfg) => ({
       message: missingRefsForCategoriesErrorMsg(
-        coreCfg.categories,
+        coreCfg.categories ?? [],
         coreCfg.plugins
       )
     })
@@ -1114,12 +1117,13 @@ function tableHtml(data) {
 
 // packages/utils/src/lib/reports/generate-md-report.ts
 function generateMdReport(report, commitData) {
+  const printCategories = report.categories.length > 0;
   return (
     // header section
     // eslint-disable-next-line prefer-template
-    reportToHeaderSection() + NEW_LINE + // overview section
-    reportToOverviewSection(report) + NEW_LINE + NEW_LINE + // categories section
-    reportToCategoriesSection(report) + NEW_LINE + NEW_LINE + // audits section
+    reportToHeaderSection() + NEW_LINE + // categories overview section
+    (printCategories ? reportToOverviewSection(report) + NEW_LINE + NEW_LINE : "") + // categories section
+    (printCategories ? reportToCategoriesSection(report) + NEW_LINE + NEW_LINE : "") + // audits section
     reportToAuditsSection(report) + NEW_LINE + NEW_LINE + // about section
     reportToAboutSection(report, commitData) + NEW_LINE + NEW_LINE + // footer section
     `${FOOTER_PREFIX} ${link(README_LINK, "Code PushUp")}`
@@ -1296,7 +1300,8 @@ function addLine(line = "") {
   return line + NEW_LINE;
 }
 function generateStdoutSummary(report) {
-  return addLine(reportToHeaderSection2(report)) + addLine() + addLine(reportToDetailSection(report)) + addLine(reportToOverviewSection2(report)) + addLine(`${FOOTER_PREFIX} ${CODE_PUSHUP_DOMAIN}`);
+  const printCategories = report.categories.length > 0;
+  return addLine(reportToHeaderSection2(report)) + addLine() + addLine(reportToDetailSection(report)) + (printCategories ? addLine(reportToOverviewSection2(report)) : "") + addLine(`${FOOTER_PREFIX} ${CODE_PUSHUP_DOMAIN}`);
 }
 function reportToHeaderSection2(report) {
   const { packageName, version: version2 } = report;
@@ -1528,7 +1533,7 @@ var verboseUtils = (verbose) => ({
 
 // packages/core/package.json
 var name = "@code-pushup/core";
-var version = "0.12.1";
+var version = "0.12.3";
 
 // packages/core/src/lib/implementation/execute-plugin.ts
 import chalk4 from "chalk";
@@ -1960,6 +1965,13 @@ function yargsAutorunCommandObject() {
         }
       };
       await collectAndPersistReports(optionsWithFormat);
+      if (options2.categories.length === 0) {
+        console.info(
+          chalk5.gray(
+            "\u{1F4A1} Configure categories to see the scores in an overview table. See: https://github.com/code-pushup/cli/blob/main/packages/cli/README.md"
+          )
+        );
+      }
       if (options2.upload) {
         await upload(options2);
       } else {
@@ -1991,6 +2003,13 @@ function yargsCollectCommandObject() {
       console.info(chalk6.bold(CLI_NAME));
       console.info(chalk6.gray(`Run ${command}...`));
       await collectAndPersistReports(options2);
+      if (options2.categories.length === 0) {
+        console.info(
+          chalk6.gray(
+            "\u{1F4A1} 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: upload2 = {} } = args;
       if (Object.keys(upload2).length === 0) {
         console.info(
@@ -2077,6 +2096,7 @@ async function coreConfigMiddleware(processArgs) {
   const {
     persist: rcPersist,
     upload: rcUpload,
+    categories: rcCategories,
     ...remainingRcConfig
   } = importedRc;
   const parsedProcessArgs = {
@@ -2091,7 +2111,8 @@ async function coreConfigMiddleware(processArgs) {
       outputDir: cliPersist?.outputDir ?? rcPersist?.outputDir ?? PERSIST_OUTPUT_DIR,
       format: cliPersist?.format ?? rcPersist?.format ?? PERSIST_FORMAT,
       filename: cliPersist?.filename ?? rcPersist?.filename ?? PERSIST_FILENAME
-    }
+    },
+    categories: rcCategories ?? []
   };
   return parsedProcessArgs;
 }
@@ -2108,6 +2129,9 @@ function filterCategoryByPluginSlug(categories, {
   onlyPlugins,
   verbose = false
 }) {
+  if (categories.length === 0) {
+    return categories;
+  }
   if (!onlyPlugins?.length) {
     return categories;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-pushup/cli",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "license": "MIT",
   "bin": {
     "code-pushup": "index.js"

package/src/lib/implementation/core-config.middleware.d.ts

@@ -1,19 +1,6 @@
 import { CoreConfig } from '@code-pushup/models';
 import { GeneralCliOptions } from './global.model';
 export declare function coreConfigMiddleware<T extends Partial<GeneralCliOptions & CoreConfig>>(processArgs: T): Promise<{
-    categories: {
-        slug: string;
-        refs: {
-            slug: string;
-            weight: number;
-            type: "audit" | "group";
-            plugin: string;
-        }[];
-        title: string;
-        description?: string | undefined;
-        docsUrl?: string | undefined;
-        isBinary?: boolean | undefined;
-    }[];
     plugins: {
         slug: string;
         title: string;
@@ -222,4 +209,17 @@ export declare function coreConfigMiddleware<T extends Partial<GeneralCliOptions
         project: string;
         timeout?: number | undefined;
     } | undefined;
+    categories?: {
+        slug: string;
+        refs: {
+            slug: string;
+            weight: number;
+            type: "audit" | "group";
+            plugin: string;
+        }[];
+        title: string;
+        description?: string | undefined;
+        docsUrl?: string | undefined;
+        isBinary?: boolean | undefined;
+    }[] | undefined;
 } & import("./core-config.model").ConfigCliOptions & import("@code-pushup/core").GlobalOptions>;

package/src/lib/implementation/only-plugins.middleware.d.ts

@@ -1,20 +1,7 @@
 import { CoreConfig } from '@code-pushup/models';
 import { GeneralCliOptions } from './global.model';
 import { OnlyPluginsOptions } from './only-plugins.model';
-export declare function onlyPluginsMiddleware<T extends Partial<GeneralCliOptions & CoreConfig & OnlyPluginsOptions>>(processArgs: T): {
-    categories: {
-        slug: string;
-        refs: {
-            slug: string;
-            weight: number;
-            type: "audit" | "group";
-            plugin: string;
-        }[];
-        title: string;
-        description?: string | undefined;
-        docsUrl?: string | undefined;
-        isBinary?: boolean | undefined;
-    }[];
+export declare function onlyPluginsMiddleware<T extends Partial<GeneralCliOptions & CoreConfig & OnlyPluginsOptions>>(processArgs: T): Required<{
     plugins: {
         slug: string;
         title: string;
@@ -223,4 +210,17 @@ export declare function onlyPluginsMiddleware<T extends Partial<GeneralCliOption
         project: string;
         timeout?: number | undefined;
     } | undefined;
-} & import("./core-config.model").ConfigCliOptions & import("@code-pushup/core").GlobalOptions & OnlyPluginsOptions;
+    categories?: {
+        slug: string;
+        refs: {
+            slug: string;
+            weight: number;
+            type: "audit" | "group";
+            plugin: string;
+        }[];
+        title: string;
+        description?: string | undefined;
+        docsUrl?: string | undefined;
+        isBinary?: boolean | undefined;
+    }[] | undefined;
+}> & import("./core-config.model").ConfigCliOptions & import("@code-pushup/core").GlobalOptions & OnlyPluginsOptions;

package/src/lib/implementation/only-plugins.utils.d.ts

@@ -1,11 +1,11 @@
-import { CoreConfig } from '@code-pushup/models';
+import { CategoryConfig, CoreConfig } from '@code-pushup/models';
 export declare function filterPluginsBySlug(plugins: CoreConfig['plugins'], { onlyPlugins }: {
     onlyPlugins?: string[];
 }): CoreConfig['plugins'];
-export declare function filterCategoryByPluginSlug(categories: CoreConfig['categories'], { onlyPlugins, verbose, }: {
+export declare function filterCategoryByPluginSlug(categories: CategoryConfig[], { onlyPlugins, verbose, }: {
     onlyPlugins?: string[];
     verbose?: boolean;
-}): CoreConfig['categories'];
+}): CategoryConfig[];
 export declare function validateOnlyPluginsOption(plugins: CoreConfig['plugins'], { onlyPlugins, verbose, }: {
     onlyPlugins?: string[];
     verbose?: boolean;