@code-pushup/cli 0.49.0 → 0.50.0

package/README.md

@@ -268,12 +268,13 @@ Usage:
 Description:
 Compare 2 reports and produce a report diff file.
 
-In addition to the [Common Command Options](#common-command-options), the following options are required:
+In addition to the [Common Command Options](#common-command-options), the following options are recognized by the `compare` command:
 
-| Option         | Type     | Description                   |
-| -------------- | -------- | ----------------------------- |
-| **`--before`** | `string` | Path to source `report.json`. |
-| **`--after`**  | `string` | Path to target `report.json`. |
+| Option         | Required | Type     | Description                         |
+| -------------- | :------: | -------- | ----------------------------------- |
+| **`--before`** |   yes    | `string` | Path to source `report.json`.       |
+| **`--after`**  |   yes    | `string` | Path to target `report.json`.       |
+| **`--label`**  |    no    | `string` | Label for diff (e.g. project name). |
 
 #### `print-config` command
 
@@ -284,3 +285,17 @@ Description:
 Print the resolved configuration.
 
 Refer to the [Common Command Options](#common-command-options) for the list of available options.
+
+### `merge-diffs` command
+
+Usage:
+`code-pushup merge-diffs --files PATH_1 PATH_2 ... [options]`
+
+Description:
+Combine multiple report diffs into a single `report-diff.md`.
+
+In addition to the [Common Command Options](#common-command-options), the following options are recognized by the `merge-diffs` command:
+
+| Option        | Required | Type       | Description                       |
+| ------------- | :------: | ---------- | --------------------------------- |
+| **`--files`** |   yes    | `string[]` | List of `report-diff.json` paths. |

package/index.js

@@ -683,6 +683,8 @@ var auditResultSchema = scorableWithPluginMetaSchema.merge(
 );
 var reportsDiffSchema = z15.object({
   commits: makeComparisonSchema(commitSchema).nullable().describe("Commits identifying compared reports"),
+  portalUrl: urlSchema.optional().describe("Link to comparison page in Code PushUp portal"),
+  label: z15.string().optional().describe("Label (e.g. project name)"),
   categories: makeArraysComparisonSchema(
     categoryDiffSchema,
     categoryResultSchema,
@@ -752,8 +754,24 @@ function comparePairs(pairs, equalsFn) {
   );
 }
 
+// packages/utils/src/lib/errors.ts
+function stringifyError(error) {
+  if (error instanceof Error) {
+    if (error.name === "Error" || error.message.startsWith(error.name)) {
+      return error.message;
+    }
+    return `${error.name}: ${error.message}`;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return JSON.stringify(error);
+}
+
 // packages/utils/src/lib/execute-process.ts
-import { spawn } from "node:child_process";
+import {
+  spawn
+} from "node:child_process";
 
 // packages/utils/src/lib/reports/utils.ts
 import ansis from "ansis";
@@ -880,12 +898,12 @@ function countCategoryAudits(refs, plugins) {
   }, 0);
 }
 function compareCategoryAuditsAndGroups(a, b) {
-  if (a.weight !== b.weight) {
-    return b.weight - a.weight;
-  }
   if (a.score !== b.score) {
     return a.score - b.score;
   }
+  if (a.weight !== b.weight) {
+    return b.weight - a.weight;
+  }
   if ("value" in a && "value" in b && a.value !== b.value) {
     return b.value - a.value;
   }
@@ -977,25 +995,29 @@ var ProcessError = class extends Error {
   }
 };
 function executeProcess(cfg) {
-  const { observer, cwd, command: command2, args, ignoreExitCode = false } = cfg;
-  const { onStdout, onError, onComplete } = observer ?? {};
+  const { command: command2, args, observer, ignoreExitCode = false, ...options2 } = cfg;
+  const { onStdout, onStderr, onError, onComplete } = observer ?? {};
   const date = (/* @__PURE__ */ new Date()).toISOString();
   const start = performance.now();
   return new Promise((resolve, reject) => {
-    const process2 = spawn(command2, args, { cwd, shell: true });
+    const spawnedProcess = spawn(command2, args ?? [], {
+      shell: true,
+      ...options2
+    });
     let stdout = "";
     let stderr = "";
-    process2.stdout.on("data", (data) => {
+    spawnedProcess.stdout.on("data", (data) => {
       stdout += String(data);
-      onStdout?.(String(data));
+      onStdout?.(String(data), spawnedProcess);
     });
-    process2.stderr.on("data", (data) => {
+    spawnedProcess.stderr.on("data", (data) => {
       stderr += String(data);
+      onStderr?.(String(data), spawnedProcess);
     });
-    process2.on("error", (err) => {
+    spawnedProcess.on("error", (err) => {
       stderr += err.toString();
     });
-    process2.on("close", (code2) => {
+    spawnedProcess.on("close", (code2) => {
       const timings = { date, duration: calcDuration(start) };
       if (code2 === 0 || ignoreExitCode) {
         onComplete?.();
@@ -1569,7 +1591,10 @@ function getColumnAlignments(tableData) {
 }
 
 // packages/utils/src/lib/reports/formatting.ts
-import { MarkdownDocument, md as md2 } from "build-md";
+import {
+  MarkdownDocument,
+  md as md2
+} from "build-md";
 function tableSection(tableData, options2) {
   if (tableData.rows.length === 0) {
     return null;
@@ -1890,17 +1915,17 @@ function pluginMetaTable({
       { heading: "Version", alignment: "center" },
       { heading: "Duration", alignment: "right" }
     ],
-    plugins.map(({ title, audits, version: version2 = "", duration }) => [
+    plugins.map(({ title, audits, version: version3 = "", duration }) => [
       title,
       audits.length.toString(),
-      version2 && md4.code(version2),
+      version3 && md4.code(version3),
       formatDuration(duration)
     ])
   ];
 }
 function reportMetaTable({
   commit,
-  version: version2,
+  version: version3,
   duration,
   plugins,
   categories
@@ -1917,7 +1942,7 @@ function reportMetaTable({
     [
       [
         commit ? `${commit.message} (${commit.hash})` : "N/A",
-        md4.code(version2),
+        md4.code(version3),
         formatDuration(duration),
         plugins.length.toString(),
         categories.length.toString(),
@@ -1929,19 +1954,111 @@ function reportMetaTable({
 
 // packages/utils/src/lib/reports/generate-md-reports-diff.ts
 import {
-  MarkdownDocument as MarkdownDocument4,
-  md as md5
+  MarkdownDocument as MarkdownDocument5,
+  md as md6
 } from "build-md";
+
+// packages/utils/src/lib/reports/generate-md-reports-diff-utils.ts
+import { MarkdownDocument as MarkdownDocument4, md as md5 } from "build-md";
 var MAX_ROWS = 100;
-function generateMdReportsDiff(diff, portalUrl) {
-  return new MarkdownDocument4().$concat(
-    createDiffHeaderSection(diff, portalUrl),
-    createDiffCategoriesSection(diff),
-    createDiffGroupsSection(diff),
-    createDiffAuditsSection(diff)
-  ).toString();
+function summarizeUnchanged(token, { changed, unchanged }) {
+  const pluralizedCount = changed.length > 0 ? pluralizeToken(`other ${token}`, unchanged.length) : `All of ${pluralizeToken(token, unchanged.length)}`;
+  const pluralizedVerb = unchanged.length === 1 ? "is" : "are";
+  return `${pluralizedCount} ${pluralizedVerb} unchanged.`;
+}
+function summarizeDiffOutcomes(outcomes, token) {
+  return objectToEntries(countDiffOutcomes(outcomes)).filter(
+    (entry) => entry[0] !== "unchanged" && entry[1] > 0
+  ).map(([outcome, count]) => {
+    const formattedCount = `<strong>${count}</strong> ${pluralize(
+      token,
+      count
+    )}`;
+    switch (outcome) {
+      case "positive":
+        return `\u{1F44D} ${formattedCount} improved`;
+      case "negative":
+        return `\u{1F44E} ${formattedCount} regressed`;
+      case "mixed":
+        return `${formattedCount} changed without impacting score`;
+    }
+  }).join(", ");
+}
+function createGroupsOrAuditsDetails(token, { changed, unchanged }, ...[columns, rows]) {
+  if (changed.length === 0) {
+    return new MarkdownDocument4().paragraph(
+      summarizeUnchanged(token, { changed, unchanged })
+    );
+  }
+  return new MarkdownDocument4().table(columns, rows.slice(0, MAX_ROWS)).paragraph(
+    changed.length > MAX_ROWS && md5.italic(
+      `Only the ${MAX_ROWS} most affected ${pluralize(
+        token
+      )} are listed above for brevity.`
+    )
+  ).paragraph(
+    unchanged.length > 0 && summarizeUnchanged(token, { changed, unchanged })
+  );
+}
+function formatTitle({
+  title,
+  docsUrl
+}) {
+  if (docsUrl) {
+    return md5.link(docsUrl, title);
+  }
+  return title;
+}
+function formatPortalLink(portalUrl) {
+  return portalUrl && md5.link(portalUrl, "\u{1F575}\uFE0F See full comparison in Code PushUp portal \u{1F50D}");
+}
+function sortChanges(changes) {
+  return [...changes].sort(
+    (a, b) => Math.abs(b.scores.diff) - Math.abs(a.scores.diff) || Math.abs(b.values?.diff ?? 0) - Math.abs(a.values?.diff ?? 0)
+  );
+}
+function getDiffChanges(diff) {
+  return [
+    ...diff.categories.changed,
+    ...diff.groups.changed,
+    ...diff.audits.changed
+  ];
+}
+function changesToDiffOutcomes(changes) {
+  return changes.map((change) => {
+    if (change.scores.diff > 0) {
+      return "positive";
+    }
+    if (change.scores.diff < 0) {
+      return "negative";
+    }
+    if (change.values != null && change.values.diff !== 0) {
+      return "mixed";
+    }
+    return "unchanged";
+  });
+}
+function mergeDiffOutcomes(outcomes) {
+  if (outcomes.every((outcome) => outcome === "unchanged")) {
+    return "unchanged";
+  }
+  if (outcomes.includes("positive") && !outcomes.includes("negative")) {
+    return "positive";
+  }
+  if (outcomes.includes("negative") && !outcomes.includes("positive")) {
+    return "negative";
+  }
+  return "mixed";
 }
-function createDiffHeaderSection(diff, portalUrl) {
+function countDiffOutcomes(outcomes) {
+  return {
+    positive: outcomes.filter((outcome) => outcome === "positive").length,
+    negative: outcomes.filter((outcome) => outcome === "negative").length,
+    mixed: outcomes.filter((outcome) => outcome === "mixed").length,
+    unchanged: outcomes.filter((outcome) => outcome === "unchanged").length
+  };
+}
+function formatReportOutcome(outcome, commits) {
   const outcomeTexts = {
     positive: md5`🥳 Code PushUp report has ${md5.bold("improved")}`,
     negative: md5`😟 Code PushUp report has ${md5.bold("regressed")}`,
@@ -1950,27 +2067,91 @@ function createDiffHeaderSection(diff, portalUrl) {
     )}`,
     unchanged: md5`😐 Code PushUp report is ${md5.bold("unchanged")}`
   };
+  if (commits) {
+    const commitsText = `compared target commit ${commits.after.hash} with source commit ${commits.before.hash}`;
+    return md5`${outcomeTexts[outcome]} – ${commitsText}.`;
+  }
+  return md5`${outcomeTexts[outcome]}.`;
+}
+function compareDiffsBy(type, a, b) {
+  return sumScoreChanges(b[type].changed) - sumScoreChanges(a[type].changed) || sumConfigChanges(b[type]) - sumConfigChanges(a[type]);
+}
+function sumScoreChanges(changes) {
+  return changes.reduce(
+    (acc, { scores }) => acc + Math.abs(scores.diff),
+    0
+  );
+}
+function sumConfigChanges({
+  added,
+  removed
+}) {
+  return added.length + removed.length;
+}
+
+// packages/utils/src/lib/reports/generate-md-reports-diff.ts
+function generateMdReportsDiff(diff) {
+  return new MarkdownDocument5().$concat(
+    createDiffHeaderSection(diff),
+    createDiffCategoriesSection(diff),
+    createDiffDetailsSection(diff)
+  ).toString();
+}
+function generateMdReportsDiffForMonorepo(diffs) {
+  const diffsWithOutcomes = diffs.map((diff) => ({
+    ...diff,
+    outcome: mergeDiffOutcomes(changesToDiffOutcomes(getDiffChanges(diff)))
+  })).sort(
+    (a, b) => compareDiffsBy("categories", a, b) || compareDiffsBy("groups", a, b) || compareDiffsBy("audits", a, b) || a.label.localeCompare(b.label)
+  );
+  const unchanged = diffsWithOutcomes.filter(
+    ({ outcome }) => outcome === "unchanged"
+  );
+  const changed = diffsWithOutcomes.filter((diff) => !unchanged.includes(diff));
+  return new MarkdownDocument5().$concat(
+    createDiffHeaderSection(diffs),
+    ...changed.map(createDiffProjectSection)
+  ).$if(
+    unchanged.length > 0,
+    (doc) => doc.rule().paragraph(summarizeUnchanged("project", { unchanged, changed }))
+  ).toString();
+}
+function createDiffHeaderSection(diff) {
   const outcome = mergeDiffOutcomes(
-    changesToDiffOutcomes([
-      ...diff.categories.changed,
-      ...diff.groups.changed,
-      ...diff.audits.changed
-    ])
+    changesToDiffOutcomes(toArray(diff).flatMap(getDiffChanges))
   );
-  const styleCommits = (commits) => `compared target commit ${commits.after.hash} with source commit ${commits.before.hash}`;
-  return new MarkdownDocument4().heading(HIERARCHY.level_1, "Code PushUp").paragraph(
-    diff.commits ? md5`${outcomeTexts[outcome]} – ${styleCommits(diff.commits)}.` : outcomeTexts[outcome]
-  ).paragraph(
-    portalUrl && md5.link(portalUrl, "\u{1F575}\uFE0F See full comparison in Code PushUp portal \u{1F50D}")
+  const commits = Array.isArray(diff) ? diff[0]?.commits : diff.commits;
+  const portalUrl = Array.isArray(diff) ? void 0 : diff.portalUrl;
+  return new MarkdownDocument5().heading(HIERARCHY.level_1, "Code PushUp").paragraph(formatReportOutcome(outcome, commits)).paragraph(formatPortalLink(portalUrl));
+}
+function createDiffProjectSection(diff) {
+  return new MarkdownDocument5().heading(HIERARCHY.level_2, md6`💼 Project ${md6.code(diff.label)}`).paragraph(formatReportOutcome(diff.outcome)).paragraph(formatPortalLink(diff.portalUrl)).$concat(
+    createDiffCategoriesSection(diff, {
+      skipHeading: true,
+      skipUnchanged: true
+    }),
+    createDiffDetailsSection(diff, HIERARCHY.level_3)
   );
 }
-function createDiffCategoriesSection(diff) {
+function createDiffCategoriesSection(diff, options2) {
   const { changed, unchanged, added } = diff.categories;
+  const { skipHeading, skipUnchanged } = options2 ?? {};
   const categoriesCount = changed.length + unchanged.length + added.length;
   const hasChanges = unchanged.length < categoriesCount;
   if (categoriesCount === 0) {
     return null;
   }
+  const [columns, rows] = createCategoriesTable(diff, {
+    hasChanges,
+    skipUnchanged
+  });
+  return new MarkdownDocument5().heading(HIERARCHY.level_2, !skipHeading && "\u{1F3F7}\uFE0F Categories").table(columns, rows).paragraph(added.length > 0 && md6.italic("(\\*) New category.")).paragraph(
+    skipUnchanged && unchanged.length > 0 && summarizeUnchanged("category", { changed, unchanged })
+  );
+}
+function createCategoriesTable(diff, options2) {
+  const { changed, unchanged, added } = diff.categories;
+  const { hasChanges, skipUnchanged } = options2;
   const columns = [
     { heading: "\u{1F3F7}\uFE0F Category", alignment: "left" },
     {
@@ -1991,27 +2172,43 @@ function createDiffCategoriesSection(diff) {
     ]),
     ...added.map((category) => [
       formatTitle(category),
-      md5.italic("n/a (\\*)"),
+      md6.italic("n/a (\\*)"),
       formatScoreWithColor(category.score),
-      md5.italic("n/a (\\*)")
+      md6.italic("n/a (\\*)")
     ]),
-    ...unchanged.map((category) => [
+    ...skipUnchanged ? [] : unchanged.map((category) => [
       formatTitle(category),
       formatScoreWithColor(category.score, { skipBold: true }),
       formatScoreWithColor(category.score),
       "\u2013"
     ])
   ];
-  return new MarkdownDocument4().heading(HIERARCHY.level_2, "\u{1F3F7}\uFE0F Categories").table(
+  return [
     hasChanges ? columns : columns.slice(0, 2),
     rows.map((row) => hasChanges ? row : row.slice(0, 2))
-  ).paragraph(added.length > 0 && md5.italic("(\\*) New category."));
+  ];
+}
+function createDiffDetailsSection(diff, level = HIERARCHY.level_2) {
+  if (diff.groups.changed.length + diff.audits.changed.length === 0) {
+    return null;
+  }
+  const summary = ["group", "audit"].map(
+    (token) => summarizeDiffOutcomes(
+      changesToDiffOutcomes(diff[`${token}s`].changed),
+      token
+    )
+  ).filter(Boolean).join(", ");
+  const details2 = new MarkdownDocument5().$concat(
+    createDiffGroupsSection(diff, level),
+    createDiffAuditsSection(diff, level)
+  );
+  return new MarkdownDocument5().details(summary, details2);
 }
-function createDiffGroupsSection(diff) {
+function createDiffGroupsSection(diff, level) {
   if (diff.groups.changed.length + diff.groups.unchanged.length === 0) {
     return null;
   }
-  return new MarkdownDocument4().heading(HIERARCHY.level_2, "\u{1F5C3}\uFE0F Groups").$concat(
+  return new MarkdownDocument5().heading(level, "\u{1F5C3}\uFE0F Groups").$concat(
     createGroupsOrAuditsDetails(
       "group",
       diff.groups,
@@ -2032,8 +2229,8 @@ function createDiffGroupsSection(diff) {
     )
   );
 }
-function createDiffAuditsSection(diff) {
-  return new MarkdownDocument4().heading(HIERARCHY.level_2, "\u{1F6E1}\uFE0F Audits").$concat(
+function createDiffAuditsSection(diff, level) {
+  return new MarkdownDocument5().heading(level, "\u{1F6E1}\uFE0F Audits").$concat(
     createGroupsOrAuditsDetails(
       "audit",
       diff.audits,
@@ -2048,7 +2245,7 @@ function createDiffAuditsSection(diff) {
         formatTitle(audit.plugin),
         formatTitle(audit),
         `${scoreMarker(audit.scores.before, "square")} ${audit.displayValues.before || audit.values.before.toString()}`,
-        md5`${scoreMarker(audit.scores.after, "square")} ${md5.bold(
+        md6`${scoreMarker(audit.scores.after, "square")} ${md6.bold(
           audit.displayValues.after || audit.values.after.toString()
         )}`,
         formatValueChange(audit)
@@ -2056,96 +2253,6 @@ function createDiffAuditsSection(diff) {
     )
   );
 }
-function createGroupsOrAuditsDetails(token, { changed, unchanged }, ...[columns, rows]) {
-  if (changed.length === 0) {
-    return new MarkdownDocument4().paragraph(
-      summarizeUnchanged(token, { changed, unchanged })
-    );
-  }
-  return new MarkdownDocument4().details(
-    summarizeDiffOutcomes(changesToDiffOutcomes(changed), token),
-    md5`${md5.table(columns, rows.slice(0, MAX_ROWS))}${changed.length > MAX_ROWS ? md5.paragraph(
-      md5.italic(
-        `Only the ${MAX_ROWS} most affected ${pluralize(
-          token
-        )} are listed above for brevity.`
-      )
-    ) : ""}${unchanged.length > 0 ? md5.paragraph(summarizeUnchanged(token, { changed, unchanged })) : ""}`
-  );
-}
-function summarizeUnchanged(token, { changed, unchanged }) {
-  return [
-    changed.length > 0 ? pluralizeToken(`other ${token}`, unchanged.length) : `All of ${pluralizeToken(token, unchanged.length)}`,
-    unchanged.length === 1 ? "is" : "are",
-    "unchanged."
-  ].join(" ");
-}
-function summarizeDiffOutcomes(outcomes, token) {
-  return objectToEntries(countDiffOutcomes(outcomes)).filter(
-    (entry) => entry[0] !== "unchanged" && entry[1] > 0
-  ).map(([outcome, count]) => {
-    const formattedCount = `<strong>${count}</strong> ${pluralize(
-      token,
-      count
-    )}`;
-    switch (outcome) {
-      case "positive":
-        return `\u{1F44D} ${formattedCount} improved`;
-      case "negative":
-        return `\u{1F44E} ${formattedCount} regressed`;
-      case "mixed":
-        return `${formattedCount} changed without impacting score`;
-    }
-  }).join(", ");
-}
-function formatTitle({
-  title,
-  docsUrl
-}) {
-  if (docsUrl) {
-    return md5.link(docsUrl, title);
-  }
-  return title;
-}
-function sortChanges(changes) {
-  return [...changes].sort(
-    (a, b) => Math.abs(b.scores.diff) - Math.abs(a.scores.diff) || Math.abs(b.values?.diff ?? 0) - Math.abs(a.values?.diff ?? 0)
-  );
-}
-function changesToDiffOutcomes(changes) {
-  return changes.map((change) => {
-    if (change.scores.diff > 0) {
-      return "positive";
-    }
-    if (change.scores.diff < 0) {
-      return "negative";
-    }
-    if (change.values != null && change.values.diff !== 0) {
-      return "mixed";
-    }
-    return "unchanged";
-  });
-}
-function mergeDiffOutcomes(outcomes) {
-  if (outcomes.every((outcome) => outcome === "unchanged")) {
-    return "unchanged";
-  }
-  if (outcomes.includes("positive") && !outcomes.includes("negative")) {
-    return "positive";
-  }
-  if (outcomes.includes("negative") && !outcomes.includes("positive")) {
-    return "negative";
-  }
-  return "mixed";
-}
-function countDiffOutcomes(outcomes) {
-  return {
-    positive: outcomes.filter((outcome) => outcome === "positive").length,
-    negative: outcomes.filter((outcome) => outcome === "negative").length,
-    mixed: outcomes.filter((outcome) => outcome === "mixed").length,
-    unchanged: outcomes.filter((outcome) => outcome === "unchanged").length
-  };
-}
 
 // packages/utils/src/lib/reports/load-report.ts
 import { join as join2 } from "node:path";
@@ -2178,8 +2285,8 @@ function logStdoutSummary(report) {
   log();
 }
 function reportToHeaderSection(report) {
-  const { packageName, version: version2 } = report;
-  return `${bold4(REPORT_HEADLINE_TEXT)} - ${packageName}@${version2}`;
+  const { packageName, version: version3 } = report;
+  return `${bold4(REPORT_HEADLINE_TEXT)} - ${packageName}@${version3}`;
 }
 function logPlugins(report) {
   const { plugins } = report;
@@ -2202,7 +2309,8 @@ function logPlugins(report) {
         },
         {
           text: cyanBright(audit.displayValue || `${audit.value}`),
-          width: 10,
+          // eslint-disable-next-line no-magic-numbers
+          width: 20,
           padding: [0, 0, 0, 0]
         }
       ]);
@@ -2355,7 +2463,7 @@ var verboseUtils = (verbose = false) => ({
 
 // packages/core/package.json
 var name = "@code-pushup/core";
-var version = "0.49.0";
+var version = "0.50.0";
 
 // packages/core/src/lib/implementation/execute-plugin.ts
 import { bold as bold5 } from "ansis";
@@ -2751,7 +2859,7 @@ function selectMeta(meta) {
 }
 
 // packages/core/src/lib/compare.ts
-async function compareReportFiles(inputPaths, persistConfig, uploadConfig) {
+async function compareReportFiles(inputPaths, persistConfig, uploadConfig, label) {
   const { outputDir, filename, format } = persistConfig;
   const [reportBefore, reportAfter] = await Promise.all([
     readJsonFile(inputPaths.before),
@@ -2761,12 +2869,20 @@ async function compareReportFiles(inputPaths, persistConfig, uploadConfig) {
     before: reportSchema.parse(reportBefore),
     after: reportSchema.parse(reportAfter)
   };
-  const reportsDiff = compareReports(reports);
-  const portalUrl = uploadConfig && reportsDiff.commits && format.includes("md") ? await fetchPortalComparisonLink(uploadConfig, reportsDiff.commits) : void 0;
+  const diff = compareReports(reports);
+  if (label) {
+    diff.label = label;
+  }
+  if (uploadConfig && diff.commits) {
+    diff.portalUrl = await fetchPortalComparisonLink(
+      uploadConfig,
+      diff.commits
+    );
+  }
   return Promise.all(
     format.map(async (fmt) => {
       const outputPath = join5(outputDir, `${filename}-diff.${fmt}`);
-      const content = reportsDiffToFileContent(reportsDiff, fmt, portalUrl);
+      const content = reportsDiffToFileContent(diff, fmt);
       await ensureDirectoryExists(outputDir);
       await writeFile2(outputPath, content);
       return outputPath;
@@ -2796,12 +2912,12 @@ function compareReports(reports) {
     duration
   };
 }
-function reportsDiffToFileContent(reportsDiff, format, portalUrl) {
+function reportsDiffToFileContent(reportsDiff, format) {
   switch (format) {
     case "json":
       return JSON.stringify(reportsDiff, null, 2);
     case "md":
-      return generateMdReportsDiff(reportsDiff, portalUrl ?? void 0);
+      return generateMdReportsDiff(reportsDiff);
   }
 }
 async function fetchPortalComparisonLink(uploadConfig, commits) {
@@ -3074,6 +3190,45 @@ async function autoloadRc(tsconfig) {
   );
 }
 
+// packages/core/src/lib/merge-diffs.ts
+import { writeFile as writeFile3 } from "node:fs/promises";
+import { basename, dirname, join as join7 } from "node:path";
+async function mergeDiffs(files, persistConfig) {
+  const results = await Promise.allSettled(
+    files.map(async (file) => {
+      const json = await readJsonFile(file).catch((error) => {
+        throw new Error(
+          `Failed to read JSON file ${file} - ${stringifyError(error)}`
+        );
+      });
+      const result = await reportsDiffSchema.safeParseAsync(json);
+      if (!result.success) {
+        throw new Error(
+          `Invalid reports diff in ${file} - ${result.error.message}`
+        );
+      }
+      return { ...result.data, file };
+    })
+  );
+  results.filter(isPromiseRejectedResult).forEach(({ reason }) => {
+    ui().logger.warning(
+      `Skipped invalid report diff - ${stringifyError(reason)}`
+    );
+  });
+  const diffs = results.filter(isPromiseFulfilledResult).map(({ value }) => value);
+  const labeledDiffs = diffs.map((diff) => ({
+    ...diff,
+    label: diff.label || basename(dirname(diff.file))
+    // fallback is parent folder name
+  }));
+  const markdown = generateMdReportsDiffForMonorepo(labeledDiffs);
+  const { outputDir, filename } = persistConfig;
+  const outputPath = join7(outputDir, `${filename}-diff.md`);
+  await ensureDirectoryExists(outputDir);
+  await writeFile3(outputPath, markdown);
+  return outputPath;
+}
+
 // packages/cli/src/lib/constants.ts
 var CLI_NAME = "Code PushUp CLI";
 var CLI_SCRIPT_NAME = "code-pushup";
@@ -3207,6 +3362,10 @@ function yargsCompareOptionsDefinition() {
       describe: "Path to target report.json",
       type: "string",
       demandOption: true
+    },
+    label: {
+      describe: "Label for diff (e.g. project name)",
+      type: "string"
     }
   };
 }
@@ -3222,11 +3381,12 @@ function yargsCompareCommandObject() {
       ui().logger.log(bold9(CLI_NAME));
       ui().logger.info(gray6(`Run ${command2}...`));
       const options2 = args;
-      const { before, after, persist, upload: upload2 } = options2;
+      const { before, after, label, persist, upload: upload2 } = options2;
       const outputPaths = await compareReportFiles(
         { before, after },
         persist,
-        upload2
+        upload2,
+        label
       );
       ui().logger.info(
         `Reports diff written to ${outputPaths.map((path) => bold9(path)).join(" and ")}`
@@ -3412,6 +3572,38 @@ function yargsHistoryCommandObject() {
   };
 }
 
+// packages/cli/src/lib/merge-diffs/merge-diffs-command.ts
+import { bold as bold11, gray as gray8 } from "ansis";
+
+// packages/cli/src/lib/implementation/merge-diffs.options.ts
+function yargsMergeDiffsOptionsDefinition() {
+  return {
+    files: {
+      describe: "List of report-diff.json paths",
+      type: "array",
+      demandOption: true
+    }
+  };
+}
+
+// packages/cli/src/lib/merge-diffs/merge-diffs-command.ts
+function yargsMergeDiffsCommandObject() {
+  const command2 = "merge-diffs";
+  return {
+    command: command2,
+    describe: "Combine many report diffs into a single diff file",
+    builder: yargsMergeDiffsOptionsDefinition(),
+    handler: async (args) => {
+      ui().logger.log(bold11(CLI_NAME));
+      ui().logger.info(gray8(`Run ${command2}...`));
+      const options2 = args;
+      const { files, persist } = options2;
+      const outputPath = await mergeDiffs(files, persist);
+      ui().logger.info(`Reports diff written to ${bold11(outputPath)}`);
+    }
+  };
+}
+
 // packages/cli/src/lib/print-config/print-config-command.ts
 function yargsConfigCommandObject() {
   const command2 = "print-config";
@@ -3427,15 +3619,15 @@ function yargsConfigCommandObject() {
 }
 
 // packages/cli/src/lib/upload/upload-command.ts
-import { bold as bold11, gray as gray8 } from "ansis";
+import { bold as bold12, gray as gray9 } from "ansis";
 function yargsUploadCommandObject() {
   const command2 = "upload";
   return {
     command: command2,
     describe: "Upload report results to the portal",
     handler: async (args) => {
-      ui().logger.log(bold11(CLI_NAME));
-      ui().logger.info(gray8(`Run ${command2}...`));
+      ui().logger.log(bold12(CLI_NAME));
+      ui().logger.info(gray9(`Run ${command2}...`));
       const options2 = args;
       if (options2.upload == null) {
         renderIntegratePortalHint();
@@ -3458,7 +3650,8 @@ var commands = [
   yargsUploadCommandObject(),
   yargsHistoryCommandObject(),
   yargsCompareCommandObject(),
-  yargsConfigCommandObject()
+  yargsConfigCommandObject(),
+  yargsMergeDiffsCommandObject()
 ];
 
 // packages/cli/src/lib/implementation/core-config.middleware.ts
@@ -3670,7 +3863,7 @@ function yargsGlobalOptionsDefinition() {
       default: false
     },
     config: {
-      describe: "Path to config file, e.g. code-pushup.config.ts. By default it loads code-pushup.config.(ts|mjs|js).",
+      describe: "Path to config file. By default it loads code-pushup.config.(ts|mjs|js).",
       type: "string"
     },
     tsconfig: {
@@ -3698,8 +3891,55 @@ var groups = {
 };
 
 // packages/cli/src/lib/yargs-cli.ts
-import { bold as bold12 } from "ansis";
+import { blue, dim as dim2, green as green4 } from "ansis";
 import yargs from "yargs";
+
+// packages/cli/package.json
+var version2 = "0.50.0";
+
+// packages/cli/src/lib/implementation/formatting.ts
+import { bold as bold13, dim, green as green3 } from "ansis";
+function titleStyle(title) {
+  return `${bold13(title)}`;
+}
+function headerStyle(title) {
+  return `${green3(title)}`;
+}
+function descriptionStyle(title) {
+  return `${dim(title)}`;
+}
+function formatObjectValue(opts, propName) {
+  const description = opts[propName];
+  return {
+    ...opts,
+    ...typeof description === "string" && {
+      [propName]: descriptionStyle(description)
+    }
+  };
+}
+function formatNestedValues(options2, propName) {
+  return Object.fromEntries(
+    Object.entries(options2).map(([key, opts]) => [
+      key,
+      formatObjectValue(opts, propName)
+    ])
+  );
+}
+
+// packages/cli/src/lib/yargs-cli.ts
+var yargsDecorator = {
+  "Commands:": `${green4("Commands")}:`,
+  "Options:": `${green4("Options")}:`,
+  "Examples:": `${green4("Examples")}:`,
+  boolean: blue("boolean"),
+  count: blue("count"),
+  string: blue("string"),
+  array: blue("array"),
+  required: blue("required"),
+  "default:": `${blue("default")}:`,
+  "choices:": `${blue("choices")}:`,
+  "aliases:": `${blue("aliases")}:`
+};
 function yargsCli(argv, cfg) {
   const { usageMessage, scriptName, noExitProcess } = cfg;
   const commands2 = cfg.commands ?? [];
@@ -3708,7 +3948,7 @@ function yargsCli(argv, cfg) {
   const groups2 = cfg.groups ?? {};
   const examples = cfg.examples ?? [];
   const cli2 = yargs(argv);
-  cli2.help().version(false).alias("h", "help").check((args) => {
+  cli2.updateLocale(yargsDecorator).wrap(Math.max(TERMINAL_WIDTH, cli2.terminalWidth())).help("help", descriptionStyle("Show help")).alias("h", "help").showHelpOnFail(false).version("version", dim2`Show version`, version2).check((args) => {
     const persist = args["persist"];
     return persist == null || validatePersistFormat(persist);
   }).parserConfiguration({
@@ -3716,18 +3956,18 @@ function yargsCli(argv, cfg) {
   }).coerce(
     "config",
     (config) => Array.isArray(config) ? config.at(-1) : config
-  ).options(options2).wrap(TERMINAL_WIDTH);
+  ).options(formatNestedValues(options2, "describe"));
   if (usageMessage) {
-    cli2.usage(bold12(usageMessage));
+    cli2.usage(titleStyle(usageMessage));
   }
   if (scriptName) {
     cli2.scriptName(scriptName);
   }
   examples.forEach(
-    ([exampleName, description]) => cli2.example(exampleName, description)
+    ([exampleName, description]) => cli2.example(exampleName, descriptionStyle(description))
   );
   Object.entries(groups2).forEach(
-    ([groupName, optionNames]) => cli2.group(optionNames, groupName)
+    ([groupName, optionNames]) => cli2.group(optionNames, headerStyle(groupName))
   );
   middlewares2.forEach(({ middlewareFunction, applyBeforeValidation }) => {
     cli2.middleware(
@@ -3736,13 +3976,18 @@ function yargsCli(argv, cfg) {
     );
   });
   commands2.forEach((commandObj) => {
-    cli2.command({
-      ...commandObj,
-      handler: logErrorBeforeThrow(commandObj.handler),
-      ...typeof commandObj.builder === "function" && {
-        builder: logErrorBeforeThrow(commandObj.builder)
-      }
-    });
+    cli2.command(
+      formatObjectValue(
+        {
+          ...commandObj,
+          handler: logErrorBeforeThrow(commandObj.handler),
+          ...typeof commandObj.builder === "function" && {
+            builder: logErrorBeforeThrow(commandObj.builder)
+          }
+        },
+        "describe"
+      )
+    );
   });
   if (noExitProcess) {
     cli2.exitProcess(false);
@@ -3788,8 +4033,8 @@ var cli = (args) => yargsCli(args, {
       "Run collect skiping the coverage plugin, other plugins from config file will be included."
     ],
     [
-      "code-pushup upload --persist.outputDir=dist --persist.filename=cp-report --upload.apiKey=$CP_API_KEY",
-      "Upload dist/cp-report.json to portal using API key from environment variable"
+      "code-pushup upload --persist.outputDir=dist --upload.apiKey=$CP_API_KEY",
+      "Upload dist/report.json to portal using API key from environment variable"
     ],
     [
       "code-pushup print-config --config code-pushup.config.test.js",

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@code-pushup/cli",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "license": "MIT",
+  "description": "A CLI to run all kinds of code quality measurements to align your team with company goals",
   "bin": {
     "code-pushup": "index.js"
   },
   "dependencies": {
-    "@code-pushup/models": "0.49.0",
-    "@code-pushup/core": "0.49.0",
-    "@code-pushup/utils": "0.49.0",
+    "@code-pushup/models": "0.50.0",
+    "@code-pushup/core": "0.50.0",
+    "@code-pushup/utils": "0.50.0",
     "yargs": "^17.7.2",
     "ansis": "^3.3.0",
     "simple-git": "^3.20.0"
   },
-  "homepage": "https://github.com/code-pushup/cli#readme",
+  "homepage": "code-pushup.dev",
   "bugs": {
     "url": "https://github.com/code-pushup/cli/issues"
   },
@@ -22,33 +23,6 @@
     "url": "git+https://github.com/code-pushup/cli.git",
     "directory": "packages/cli"
   },
-  "contributors": [
-    {
-      "name": "Igor Katsuba",
-      "email": "igor@katsuba.dev",
-      "url": "https://katsuba.dev"
-    },
-    {
-      "name": "Kateřina Pilátová",
-      "email": "katerina.pilatova@flowup.cz",
-      "url": "https://github.com/Tlacenka"
-    },
-    {
-      "name": "Matěj Chalk",
-      "email": "matej.chalk@flowup.cz",
-      "url": "https://github.com/matejchalk"
-    },
-    {
-      "name": "Michael Hladky",
-      "email": "michael.hladky@push-based.io",
-      "url": "https://push-based.io"
-    },
-    {
-      "name": "Michael Seredenko",
-      "email": "misha.seredenko@push-based.io",
-      "url": "https://github.com/MishaSeredenkoPushBased"
-    }
-  ],
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts"

package/src/lib/autorun/autorun-command.d.ts

@@ -1,4 +1,4 @@
-import { ArgumentsCamelCase } from 'yargs';
+import type { ArgumentsCamelCase } from 'yargs';
 export declare function yargsAutorunCommandObject(): {
     command: string;
     describe: string;

package/src/lib/collect/collect-command.d.ts

@@ -1,3 +1,3 @@
-import { CommandModule } from 'yargs';
+import type { CommandModule } from 'yargs';
 export declare function yargsCollectCommandObject(): CommandModule;
 export declare function renderUploadAutorunHint(): void;

package/src/lib/commands.d.ts

@@ -1,2 +1,2 @@
-import { CommandModule } from 'yargs';
+import type { CommandModule } from 'yargs';
 export declare const commands: CommandModule[];

package/src/lib/compare/compare-command.d.ts

@@ -1,7 +1,6 @@
-import { CompareOptions } from '../implementation/compare.model';
 export declare function yargsCompareCommandObject(): {
     command: string;
     describe: string;
-    builder: Record<keyof CompareOptions, import("yargs").Options>;
+    builder: Record<"label" | keyof import("@code-pushup/utils").Diff<string>, import("yargs").Options>;
     handler: (args: unknown) => Promise<void>;
 };

package/src/lib/history/history.model.d.ts

@@ -1,5 +1,5 @@
-import { type LogOptions } from 'simple-git';
-import { HistoryOnlyOptions } from '@code-pushup/core';
+import type { LogOptions } from 'simple-git';
+import type { HistoryOnlyOptions } from '@code-pushup/core';
 export type HistoryCliOptions = {
     targetBranch?: string;
     onlySemverTags?: boolean;

package/src/lib/history/history.options.d.ts

@@ -1,3 +1,3 @@
-import { Options } from 'yargs';
-import { HistoryCliOptions } from './history.model';
+import type { Options } from 'yargs';
+import type { HistoryCliOptions } from './history.model';
 export declare function yargsHistoryOptionsDefinition(): Record<keyof HistoryCliOptions, Options>;

package/src/lib/history/utils.d.ts

@@ -1,3 +1,3 @@
-import { HistoryOptions } from '@code-pushup/core';
-import { HistoryCliOptions } from './history.model';
+import type { HistoryOptions } from '@code-pushup/core';
+import type { HistoryCliOptions } from './history.model';
 export declare function normalizeHashOptions(processArgs: HistoryCliOptions & HistoryOptions): Promise<HistoryCliOptions & HistoryOptions>;

package/src/lib/implementation/compare.model.d.ts

@@ -1,2 +1,4 @@
-import { Diff } from '@code-pushup/utils';
-export type CompareOptions = Diff<string>;
+import type { Diff } from '@code-pushup/utils';
+export type CompareOptions = Diff<string> & {
+    label?: string;
+};

package/src/lib/implementation/compare.options.d.ts

@@ -1,3 +1,3 @@
-import { Options } from 'yargs';
+import type { Options } from 'yargs';
 import type { CompareOptions } from './compare.model';
 export declare function yargsCompareOptionsDefinition(): Record<keyof CompareOptions, Options>;

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

@@ -1,8 +1,8 @@
-import { CoreConfig, Format } from '@code-pushup/models';
-import { CoreConfigCliOptions } from './core-config.model';
-import { GeneralCliOptions } from './global.model';
-import { OnlyPluginsOptions } from './only-plugins.model';
-import { SkipPluginsOptions } from './skip-plugins.model';
+import { type CoreConfig, type Format } from '@code-pushup/models';
+import type { CoreConfigCliOptions } from './core-config.model';
+import type { GeneralCliOptions } from './global.model';
+import type { OnlyPluginsOptions } from './only-plugins.model';
+import type { SkipPluginsOptions } from './skip-plugins.model';
 export type CoreConfigMiddlewareOptions = GeneralCliOptions & CoreConfigCliOptions & OnlyPluginsOptions & SkipPluginsOptions;
 export declare function coreConfigMiddleware<T extends CoreConfigMiddlewareOptions>(processArgs: T): Promise<GeneralCliOptions & CoreConfig & OnlyPluginsOptions & SkipPluginsOptions>;
 export declare const normalizeFormats: (formats?: string[]) => Format[];

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

@@ -1,5 +1,5 @@
-import { Options } from 'yargs';
-import { PersistConfigCliOptions, UploadConfigCliOptions } from './core-config.model';
+import type { Options } from 'yargs';
+import type { PersistConfigCliOptions, UploadConfigCliOptions } from './core-config.model';
 export declare function yargsCoreConfigOptionsDefinition(): Record<keyof (PersistConfigCliOptions & UploadConfigCliOptions), Options>;
 export declare function yargsPersistConfigOptionsDefinition(): Record<keyof PersistConfigCliOptions, Options>;
 export declare function yargsUploadConfigOptionsDefinition(): Record<keyof UploadConfigCliOptions, Options>;

package/src/lib/implementation/formatting.d.ts

@@ -0,0 +1,11 @@
+export declare function titleStyle(title: string): string;
+export declare function headerStyle(title: string): string;
+export declare function descriptionStyle(title: string): string;
+export declare function formatObjectValue<T>(opts: T, propName: keyof T): T & {
+    [x: string]: string;
+};
+export declare function formatNestedValues<T>(options: Record<string, T>, propName: keyof T): {
+    [k: string]: T & {
+        [x: string]: string;
+    };
+};

package/src/lib/implementation/global.model.d.ts

@@ -1,3 +1,3 @@
-import { GlobalOptions } from '@code-pushup/core';
-import { ConfigCliOptions } from './core-config.model';
+import type { GlobalOptions } from '@code-pushup/core';
+import type { ConfigCliOptions } from './core-config.model';
 export type GeneralCliOptions = ConfigCliOptions & GlobalOptions;

package/src/lib/implementation/global.options.d.ts

@@ -1,3 +1,3 @@
-import { Options } from 'yargs';
-import { GeneralCliOptions } from './global.model';
+import type { Options } from 'yargs';
+import type { GeneralCliOptions } from './global.model';
 export declare function yargsGlobalOptionsDefinition(): Record<keyof GeneralCliOptions, Options>;

package/src/lib/implementation/merge-diffs.model.d.ts

@@ -0,0 +1,3 @@
+export type MergeDiffsOptions = {
+    files: string[];
+};

package/src/lib/implementation/merge-diffs.options.d.ts

@@ -0,0 +1,3 @@
+import type { Options } from 'yargs';
+import type { MergeDiffsOptions } from './merge-diffs.model';
+export declare function yargsMergeDiffsOptionsDefinition(): Record<keyof MergeDiffsOptions, Options>;

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

@@ -1,2 +1,2 @@
-import { OnlyPluginsOptions } from './only-plugins.model';
+import type { OnlyPluginsOptions } from './only-plugins.model';
 export declare function onlyPluginsMiddleware<T extends OnlyPluginsOptions>(originalProcessArgs: T): T;

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

@@ -1,5 +1,5 @@
-import { GlobalOptions } from '@code-pushup/core';
-import { CoreConfig } from '@code-pushup/models';
+import type { GlobalOptions } from '@code-pushup/core';
+import type { CoreConfig } from '@code-pushup/models';
 export type OnlyPluginsCliOptions = {
     onlyPlugins?: string[];
 };

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

@@ -1,3 +1,4 @@
-import { Options } from 'yargs';
+import type { Options } from 'yargs';
+import type { OnlyPluginsCliOptions } from './only-plugins.model';
 export declare const onlyPluginsOption: Options;
-export declare function yargsOnlyPluginsOptionsDefinition(): Record<'onlyPlugins', Options>;
+export declare function yargsOnlyPluginsOptionsDefinition(): Record<keyof OnlyPluginsCliOptions, Options>;

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

@@ -1,2 +1,2 @@
-import { SkipPluginsOptions } from './skip-plugins.model';
+import type { SkipPluginsOptions } from './skip-plugins.model';
 export declare function skipPluginsMiddleware<T extends SkipPluginsOptions>(originalProcessArgs: T): T;

package/src/lib/implementation/skip-plugins.model.d.ts

@@ -1,5 +1,5 @@
-import { GlobalOptions } from '@code-pushup/core';
-import { CoreConfig } from '@code-pushup/models';
+import type { GlobalOptions } from '@code-pushup/core';
+import type { CoreConfig } from '@code-pushup/models';
 export type SkipPluginsCliOptions = {
     skipPlugins?: string[];
 };

package/src/lib/implementation/skip-plugins.options.d.ts

@@ -1,3 +1,4 @@
-import { Options } from 'yargs';
+import type { Options } from 'yargs';
+import type { SkipPluginsCliOptions } from './skip-plugins.model';
 export declare const skipPluginsOption: Options;
-export declare function yargsSkipPluginsOptionsDefinition(): Record<'skipPlugins', Options>;
+export declare function yargsSkipPluginsOptionsDefinition(): Record<keyof SkipPluginsCliOptions, Options>;

package/src/lib/merge-diffs/merge-diffs-command.d.ts

@@ -0,0 +1,6 @@
+export declare function yargsMergeDiffsCommandObject(): {
+    command: string;
+    describe: string;
+    builder: Record<"files", import("yargs").Options>;
+    handler: (args: unknown) => Promise<void>;
+};

package/src/lib/middlewares.d.ts

@@ -1,4 +1,4 @@
-import { MiddlewareFunction } from 'yargs';
+import type { MiddlewareFunction } from 'yargs';
 export declare const middlewares: {
     middlewareFunction: MiddlewareFunction;
     applyBeforeValidation: boolean;

package/src/lib/upload/upload-command.d.ts

@@ -1,4 +1,4 @@
-import { ArgumentsCamelCase } from 'yargs';
+import type { ArgumentsCamelCase } from 'yargs';
 export declare function yargsUploadCommandObject(): {
     command: string;
     describe: string;

package/src/lib/yargs-cli.d.ts

@@ -1,4 +1,17 @@
-import { Argv, CommandModule, Options } from 'yargs';
+import { type Argv, type CommandModule, type Options } from 'yargs';
+export declare const yargsDecorator: {
+    'Commands:': string;
+    'Options:': string;
+    'Examples:': string;
+    boolean: string;
+    count: string;
+    string: string;
+    array: string;
+    required: string;
+    'default:': string;
+    'choices:': string;
+    'aliases:': string;
+};
 /**
  * returns configurable yargs CLI for code-pushup
  *