@code-pushup/ci 0.53.1 → 0.55.0

package/README.md

@@ -14,10 +14,10 @@
 
 This package exports **provider-agnostic core logic for running Code PushUp in CI pipelines**. It serves as the base for the following provider integrations:
 
-|                |                                                                                   |
-| :------------- | :-------------------------------------------------------------------------------- |
-| GitHub Actions | [`code-pushup/github-action`](https://github.com/marketplace/actions/code-pushup) |
-| GitLab CI/CD   | _coming soon_                                                                     |
+|                |                                                                                                     |
+| :------------- | :-------------------------------------------------------------------------------------------------- |
+| GitHub Actions | [`code-pushup/github-action`](https://github.com/marketplace/actions/code-pushup)                   |
+| GitLab CI/CD   | [`code-pushup/gitlab-pipelines-template`](https://gitlab.com/code-pushup/gitlab-pipelines-template) |
 
 ## Setup
 
@@ -74,13 +74,13 @@ This will additionally compare reports from both source and target branches and
 The PR flow requires interacting with the Git provider's API to post a comparison comment.
 Wrap these requests in functions and pass them in as an object which configures the provider.
 
-| Property                 | Required | Type                                             | Description                                                                                                              |
-| :----------------------- | :------: | :----------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
-| `createComment`          |   yes    | `(body: string) => Promise<Comment>`             | Posts a new comment to PR                                                                                                |
-| `updateComment`          |   yes    | `(id: number, body: string) => Promise<Comment>` | Updates existing PR comment                                                                                              |
-| `listComments`           |   yes    | `() => Promise<Comment[]>`                       | Fetches all comments from PR                                                                                             |
-| `maxCommentChars`        |   yes    | `number`                                         | Character limit for comment body                                                                                         |
-| `downloadReportArtifact` |    no    | `() => Promise<string \| null>`                  | Fetches previous report for base branch (returns path to downloaded `report.json`), used as cache to speed up comparison |
+| Property                 | Required | Type                                             | Description                                                                                                          |
+| :----------------------- | :------: | :----------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
+| `createComment`          |   yes    | `(body: string) => Promise<Comment>`             | Posts a new comment to PR                                                                                            |
+| `updateComment`          |   yes    | `(id: number, body: string) => Promise<Comment>` | Updates existing PR comment                                                                                          |
+| `listComments`           |   yes    | `() => Promise<Comment[]>`                       | Fetches all comments from PR                                                                                         |
+| `maxCommentChars`        |   yes    | `number`                                         | Character limit for comment body                                                                                     |
+| `downloadReportArtifact` |    no    | `(project?: string) => Promise<string \| null>`  | Fetches previous (root/project) `report.json` for base branch and returns path, used as cache to speed up comparison |
 
 A `Comment` object has the following required properties:
 
@@ -94,20 +94,23 @@ A `Comment` object has the following required properties:
 
 Optionally, you can override default options for further customization:
 
-| Property          | Type                      | Default                          | Description                                                                       |
-| :---------------- | :------------------------ | :------------------------------- | :-------------------------------------------------------------------------------- |
-| `monorepo`        | `boolean \| MonorepoTool` | `false`                          | Enables [monorepo mode](#monorepo-mode)                                           |
-| `projects`        | `string[] \| null`        | `null`                           | Custom projects configuration for [monorepo mode](#monorepo-mode)                 |
-| `task`            | `string`                  | `'code-pushup'`                  | Name of command to run Code PushUp per project in [monorepo mode](#monorepo-mode) |
-| `directory`       | `string`                  | `process.cwd()`                  | Directory in which Code PushUp CLI should run                                     |
-| `config`          | `string \| null`          | `null` [^1]                      | Path to config file (`--config` option)                                           |
-| `silent`          | `boolean`                 | `false`                          | Toggles if logs from CLI commands are printed                                     |
-| `bin`             | `string`                  | `'npx --no-install code-pushup'` | Command for executing Code PushUp CLI                                             |
-| `detectNewIssues` | `boolean`                 | `true`                           | Toggles if new issues should be detected and returned in `newIssues` property     |
-| `logger`          | `Logger`                  | `console`                        | Logger for reporting progress and encountered problems                            |
+| Property          | Type                      | Default                          | Description                                                                          |
+| :---------------- | :------------------------ | :------------------------------- | :----------------------------------------------------------------------------------- |
+| `monorepo`        | `boolean \| MonorepoTool` | `false`                          | Enables [monorepo mode](#monorepo-mode)                                              |
+| `projects`        | `string[] \| null`        | `null`                           | Custom projects configuration for [monorepo mode](#monorepo-mode)                    |
+| `task`            | `string`                  | `'code-pushup'`                  | Name of command to run Code PushUp per project in [monorepo mode](#monorepo-mode)    |
+| `directory`       | `string`                  | `process.cwd()`                  | Directory in which Code PushUp CLI should run                                        |
+| `config`          | `string \| null`          | `null` [^1]                      | Path to config file (`--config` option)                                              |
+| `silent`          | `boolean`                 | `false`                          | Toggles if logs from CLI commands are printed                                        |
+| `bin`             | `string`                  | `'npx --no-install code-pushup'` | Command for executing Code PushUp CLI                                                |
+| `detectNewIssues` | `boolean`                 | `true`                           | Toggles if new issues should be detected and returned in `newIssues` property        |
+| `logger`          | `Logger`                  | `console`                        | Logger for reporting progress and encountered problems                               |
+| `output`          | `string`                  | `'.code-pushup'`                 | Directory where Code PushUp reports will be created (interpolates project name [^2]) |
 
 [^1]: By default, the `code-pushup.config` file is autodetected as described in [`@code-pushup/cli` docs](../cli/README.md#configuration).
 
+[^2]: In monorepo mode, any occurrence of `{project}` in the `output` path will be replaced with a project name. This separation of folders per project (e.g. `output: '.code-pushup/{project}'`) may be useful for caching purposes.
+
 The `Logger` object has the following required properties:
 
 | Property | Type                        | Description        |

package/index.js

@@ -36,7 +36,7 @@ function exists(value) {
   return value != null;
 }
 function getMissingRefsForCategories(categories, plugins) {
-  if (categories.length === 0) {
+  if (!categories || categories.length === 0) {
     return false;
   }
   const auditRefsFromCategory = categories.flatMap(
@@ -113,7 +113,6 @@ var fileNameSchema = z.string().trim().regex(filenameRegex, {
   message: `The filename has to be valid`
 }).min(1, { message: "file name is invalid" });
 var positiveIntSchema = z.number().int().positive();
-var nonnegativeIntSchema = z.number().int().nonnegative();
 var nonnegativeNumberSchema = z.number().nonnegative();
 function packageVersionSchema(options) {
   const { versionDescription = "NPM version of the package", required } = options ?? {};
@@ -536,12 +535,9 @@ var unrefinedCoreConfigSchema = z14.object({
 var coreConfigSchema = refineCoreConfig(unrefinedCoreConfigSchema);
 function refineCoreConfig(schema) {
   return schema.refine(
-    (coreCfg) => !getMissingRefsForCategories(coreCfg.categories ?? [], coreCfg.plugins),
-    (coreCfg) => ({
-      message: missingRefsForCategoriesErrorMsg(
-        coreCfg.categories ?? [],
-        coreCfg.plugins
-      )
+    ({ categories, plugins }) => !getMissingRefsForCategories(categories, plugins),
+    ({ categories, plugins }) => ({
+      message: missingRefsForCategoriesErrorMsg(categories, plugins)
     })
   );
 }
@@ -598,19 +594,16 @@ var reportSchema = packageVersionSchema({
 ).merge(
   z15.object(
     {
-      categories: z15.array(categoryConfigSchema),
       plugins: z15.array(pluginReportSchema).min(1),
+      categories: z15.array(categoryConfigSchema).optional(),
       commit: commitSchema.describe("Git commit for which report was collected").nullable()
     },
     { description: "Collect output data" }
   )
 ).refine(
-  (report) => !getMissingRefsForCategories(report.categories, report.plugins),
-  (report) => ({
-    message: missingRefsForCategoriesErrorMsg(
-      report.categories,
-      report.plugins
-    )
+  ({ categories, plugins }) => !getMissingRefsForCategories(categories, plugins),
+  ({ categories, plugins }) => ({
+    message: missingRefsForCategoriesErrorMsg(categories, plugins)
   })
 );
 
@@ -662,7 +655,7 @@ var auditDiffSchema = scorableWithPluginDiffSchema.merge(
   z16.object({
     values: makeComparisonSchema(auditValueSchema).merge(
       z16.object({
-        diff: z16.number().int().describe("Value change (`values.after - values.before`)")
+        diff: z16.number().describe("Value change (`values.after - values.before`)")
       })
     ).describe("Audit `value` comparison"),
     displayValues: makeComparisonSchema(auditDisplayValueSchema).describe(
@@ -756,6 +749,7 @@ function executeProcess(cfg) {
   return new Promise((resolve, reject) => {
     const spawnedProcess = spawn(command, args ?? [], {
       shell: true,
+      windowsHide: true,
       ...options
     });
     let stdout = "";
@@ -1171,10 +1165,11 @@ import { simpleGit as simpleGit4 } from "simple-git";
 import path from "node:path";
 function persistCliOptions({
   directory,
-  project
+  project,
+  output
 }) {
   return [
-    `--persist.outputDir=${path.join(directory, DEFAULT_PERSIST_OUTPUT_DIR)}`,
+    `--persist.outputDir=${path.join(directory, output)}`,
     `--persist.filename=${createFilename(project)}`,
     ...DEFAULT_PERSIST_FORMAT.map((format) => `--persist.format=${format}`)
   ];
@@ -1183,9 +1178,10 @@ function persistedCliFiles({
   directory,
   isDiff,
   project,
-  formats
+  formats,
+  output
 }) {
-  const rootDir = path.join(directory, DEFAULT_PERSIST_OUTPUT_DIR);
+  const rootDir = path.join(directory, output);
   const filename = isDiff ? `${createFilename(project)}-diff` : createFilename(project);
   const filePaths = (formats ?? DEFAULT_PERSIST_FORMAT).reduce(
     (acc, format) => ({
@@ -1218,24 +1214,25 @@ async function runCollect({
   config,
   directory,
   silent,
-  project
+  project,
+  output
 }) {
   const { stdout } = await executeProcess({
     command: bin,
     args: [
       ...config ? [`--config=${config}`] : [],
-      ...persistCliOptions({ directory, project })
+      ...persistCliOptions({ directory, project, output })
     ],
     cwd: directory
   });
   if (!silent) {
     console.info(stdout);
   }
-  return persistedCliFiles({ directory, project });
+  return persistedCliFiles({ directory, project, output });
 }
 
 // packages/ci/src/lib/cli/commands/compare.ts
-async function runCompare({ before, after, label }, { bin, config, directory, silent, project }) {
+async function runCompare({ before, after, label }, { bin, config, directory, silent, project, output }) {
   const { stdout } = await executeProcess({
     command: bin,
     args: [
@@ -1244,32 +1241,37 @@ async function runCompare({ before, after, label }, { bin, config, directory, si
       `--after=${after}`,
       ...label ? [`--label=${label}`] : [],
       ...config ? [`--config=${config}`] : [],
-      ...persistCliOptions({ directory, project })
+      ...persistCliOptions({ directory, project, output })
     ],
     cwd: directory
   });
   if (!silent) {
     console.info(stdout);
   }
-  return persistedCliFiles({ directory, isDiff: true, project });
+  return persistedCliFiles({ directory, isDiff: true, project, output });
 }
 
 // packages/ci/src/lib/cli/commands/merge-diffs.ts
-async function runMergeDiffs(files, { bin, config, directory, silent }) {
+async function runMergeDiffs(files, { bin, config, directory, silent, output }) {
   const { stdout } = await executeProcess({
     command: bin,
     args: [
       "merge-diffs",
       ...files.map((file) => `--files=${file}`),
       ...config ? [`--config=${config}`] : [],
-      ...persistCliOptions({ directory })
+      ...persistCliOptions({ directory, output })
     ],
     cwd: directory
   });
   if (!silent) {
     console.info(stdout);
   }
-  return persistedCliFiles({ directory, isDiff: true, formats: ["md"] });
+  return persistedCliFiles({
+    directory,
+    isDiff: true,
+    formats: ["md"],
+    output
+  });
 }
 
 // packages/ci/src/lib/cli/commands/print-config.ts
@@ -1296,7 +1298,8 @@ function createCommandContext(settings, project) {
     bin: project?.bin ?? settings.bin,
     directory: project?.directory ?? settings.directory,
     config: settings.config,
-    silent: settings.silent
+    silent: settings.silent,
+    output: settings.output.replaceAll("{project}", project?.name ?? "")
   };
 }
 
@@ -1350,7 +1353,8 @@ var DEFAULT_SETTINGS = {
   silent: false,
   debug: false,
   detectNewIssues: true,
-  logger: console
+  logger: console,
+  output: DEFAULT_PERSIST_OUTPUT_DIR
 };
 
 // packages/ci/src/lib/git.ts
@@ -1510,6 +1514,9 @@ function createIssuesSortCompareFn(report) {
   return (a, b) => getAuditImpactValue(b, report) - getAuditImpactValue(a, report);
 }
 function getAuditImpactValue({ audit, plugin }, report) {
+  if (!report.categories) {
+    return 0;
+  }
   return report.categories.map((category) => {
     const weights = category.refs.map((ref) => {
       if (ref.plugin !== plugin.slug) {
@@ -1519,17 +1526,20 @@ function getAuditImpactValue({ audit, plugin }, report) {
         case "audit":
           return ref.slug === audit.slug ? ref.weight : 0;
         case "group":
-          const group = report.plugins.find(({ slug }) => slug === ref.plugin)?.groups?.find(({ slug }) => slug === ref.slug);
-          if (!group?.refs.length) {
-            return 0;
-          }
-          const groupRatio = (group.refs.find(({ slug }) => slug === audit.slug)?.weight ?? 0) / group.refs.reduce((acc, { weight }) => acc + weight, 0);
-          return ref.weight * groupRatio;
+          return calculateGroupImpact(ref, audit, report);
       }
     });
     return weights.reduce((acc, weight) => acc + weight, 0) / category.refs.reduce((acc, { weight }) => acc + weight, 0);
   }).reduce((acc, value) => acc + value, 0);
 }
+function calculateGroupImpact(ref, audit, report) {
+  const group = report.plugins.find(({ slug }) => slug === ref.plugin)?.groups?.find(({ slug }) => slug === ref.slug);
+  if (!group?.refs.length) {
+    return 0;
+  }
+  const groupRatio = (group.refs.find(({ slug }) => slug === audit.slug)?.weight ?? 0) / group.refs.reduce((acc, { weight }) => acc + weight, 0);
+  return ref.weight * groupRatio;
+}
 
 // packages/ci/src/lib/run.ts
 async function runInCI(refs, api, options, git = simpleGit4()) {
@@ -1611,7 +1621,7 @@ async function runOnProject(args) {
     return noDiffOutput;
   }
   logger.info(
-    `PR detected, preparing to compare base branch ${base.ref} to head ${head.ref}`
+    `PR/MR detected, preparing to compare base branch ${base.ref} to head ${head.ref}`
   );
   const prevReport = await collectPreviousReport({ ...args, base, ctx });
   if (!prevReport) {
@@ -1652,9 +1662,13 @@ async function runOnProject(args) {
   return { ...diffOutput, newIssues };
 }
 async function collectPreviousReport(args) {
-  const { base, api, settings, ctx, git } = args;
+  const { project, base, api, settings, ctx, git } = args;
   const logger = settings.logger;
-  const cachedBaseReport = await api.downloadReportArtifact?.();
+  const cachedBaseReport = await api.downloadReportArtifact?.(project?.name).catch((error) => {
+    logger.warn(
+      `Error when downloading previous report artifact, skipping - ${stringifyError(error)}`
+    );
+  });
   if (api.downloadReportArtifact != null) {
     logger.info(
       `Previous report artifact ${cachedBaseReport ? "found" : "not found"}`
@@ -1687,7 +1701,7 @@ async function collectPreviousReport(args) {
     const prevReport = await fs.readFile(prevReportPath, "utf8");
     logger.debug(`Collected previous report at ${prevReportPath}`);
     await git.checkout(["-f", "-"]);
-    logger.info("Switched back to PR branch");
+    logger.info("Switched back to PR/MR branch");
     return prevReport;
   }
 }
@@ -1706,7 +1720,7 @@ async function findNewIssues(args) {
     changedFiles
   });
   logger.debug(
-    `Found ${issues.length} relevant issues for ${Object.keys(changedFiles).length} changed files and created GitHub annotations`
+    `Found ${issues.length} relevant issues for ${Object.keys(changedFiles).length} changed files`
   );
   return issues;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-pushup/ci",
-  "version": "0.53.1",
+  "version": "0.55.0",
   "description": "CI automation logic for Code PushUp (provider-agnostic)",
   "license": "MIT",
   "homepage": "https://github.com/code-pushup/cli/tree/main/packages/ci#readme",
@@ -28,8 +28,8 @@
   "main": "./index.js",
   "types": "./src/index.d.ts",
   "dependencies": {
-    "@code-pushup/models": "0.53.1",
-    "@code-pushup/utils": "0.53.1",
+    "@code-pushup/models": "0.55.0",
+    "@code-pushup/utils": "0.55.0",
     "glob": "^10.4.5",
     "simple-git": "^3.20.0",
     "yaml": "^2.5.1"

package/src/lib/cli/commands/collect.d.ts

@@ -1,3 +1,3 @@
 import type { CommandContext } from '../context';
 import { type PersistedCliFiles } from '../persist';
-export declare function runCollect({ bin, config, directory, silent, project, }: CommandContext): Promise<PersistedCliFiles>;
+export declare function runCollect({ bin, config, directory, silent, project, output, }: CommandContext): Promise<PersistedCliFiles>;

package/src/lib/cli/commands/compare.d.ts

@@ -5,5 +5,5 @@ type CompareOptions = {
     after: string;
     label?: string;
 };
-export declare function runCompare({ before, after, label }: CompareOptions, { bin, config, directory, silent, project }: CommandContext): Promise<PersistedCliFiles>;
+export declare function runCompare({ before, after, label }: CompareOptions, { bin, config, directory, silent, project, output }: CommandContext): Promise<PersistedCliFiles>;
 export {};

package/src/lib/cli/commands/merge-diffs.d.ts

@@ -1,3 +1,3 @@
 import type { CommandContext } from '../context';
 import { type PersistedCliFiles } from '../persist';
-export declare function runMergeDiffs(files: string[], { bin, config, directory, silent }: CommandContext): Promise<PersistedCliFiles<'md'>>;
+export declare function runMergeDiffs(files: string[], { bin, config, directory, silent, output }: CommandContext): Promise<PersistedCliFiles<'md'>>;

package/src/lib/cli/context.d.ts

@@ -1,6 +1,6 @@
 import type { Settings } from '../models';
 import type { ProjectConfig } from '../monorepo';
-export type CommandContext = Pick<Settings, 'bin' | 'config' | 'directory' | 'silent'> & {
+export type CommandContext = Pick<Settings, 'bin' | 'config' | 'directory' | 'silent' | 'output'> & {
     project?: string;
 };
 export declare function createCommandContext(settings: Settings, project: ProjectConfig | null | undefined): CommandContext;

package/src/lib/cli/persist.d.ts

@@ -8,14 +8,20 @@ export type PersistedCliFiles<T extends Format = Format> = PersistedCliFilesForm
 export type PersistedCliFilesFormats<T extends Format = Format> = {
     [F in T as `${F}FilePath`]: string;
 };
-export declare function persistCliOptions({ directory, project, }: {
+export declare function persistCliOptions({ directory, project, output, }: {
     directory: string;
     project?: string;
+    output: string;
 }): string[];
-export declare function persistedCliFiles<TFormat extends Format = Format>({ directory, isDiff, project, formats, }: {
+export declare function persistedCliFiles<TFormat extends Format = Format>({ directory, isDiff, project, formats, output, }: {
     directory: string;
     isDiff?: boolean;
     project?: string;
     formats?: TFormat[];
+    output: string;
 }): PersistedCliFiles<TFormat>;
-export declare function findPersistedFiles(rootDir: string, files: string[], project?: string): PersistedCliFiles;
+export declare function findPersistedFiles({ rootDir, files, project, }: {
+    rootDir: string;
+    files: string[];
+    project?: string;
+}): PersistedCliFiles;

package/src/lib/issues.d.ts

@@ -1,4 +1,4 @@
-import type { Audit, Issue, PluginMeta, Report, ReportsDiff } from '@code-pushup/models';
+import type { Audit, CategoryRef, Issue, PluginMeta, Report, ReportsDiff } from '@code-pushup/models';
 import { type ChangedFiles } from './git';
 export type SourceFileIssue = Required<Issue> & IssueContext;
 type IssueContext = {
@@ -13,4 +13,5 @@ export declare function filterRelevantIssues({ currReport, prevReport, reportsDi
 }): SourceFileIssue[];
 export declare function issuesMatch(prev: SourceFileIssue, curr: SourceFileIssue, changedFiles: ChangedFiles): boolean;
 export declare function getAuditImpactValue({ audit, plugin }: IssueContext, report: Report): number;
+export declare function calculateGroupImpact(ref: CategoryRef, audit: Audit, report: Report): number;
 export {};

package/src/lib/models.d.ts

@@ -15,6 +15,7 @@ export type Options = {
     debug?: boolean;
     detectNewIssues?: boolean;
     logger?: Logger;
+    output?: string;
 };
 /**
  * {@link Options} with filled-in defaults.
@@ -33,13 +34,13 @@ export type GitRefs = {
  */
 export type ProviderAPIClient = {
     maxCommentChars: number;
-    downloadReportArtifact?: () => Promise<string | null>;
+    downloadReportArtifact?: (project?: string) => Promise<string | null>;
     listComments: () => Promise<Comment[]>;
     updateComment: (id: number, body: string) => Promise<Comment>;
     createComment: (body: string) => Promise<Comment>;
 };
 /**
- * PR comment from {@link ProviderAPIClient}
+ * PR/MR comment from {@link ProviderAPIClient}
  */
 export type Comment = {
     id: number;