@code-pushup/cli 0.26.1 → 0.28.0

package/index.js

@@ -57,7 +57,7 @@ function getMissingRefsForCategories(categories, plugins) {
     ({ refs }) => refs.filter(({ type }) => type === "group").map(({ plugin, slug }) => `${plugin}#${slug} (group)`)
   );
   const groupRefsFromPlugins = plugins.flatMap(
-    ({ groups, slug: pluginSlug }) => Array.isArray(groups) ? groups.map(({ slug }) => `${pluginSlug}#${slug} (group)`) : []
+    ({ groups: groups2, slug: pluginSlug }) => Array.isArray(groups2) ? groups2.map(({ slug }) => `${pluginSlug}#${slug} (group)`) : []
   );
   const missingGroupRefs = hasMissingStrings(
     groupRefsFromCategory,
@@ -92,6 +92,9 @@ var descriptionSchema = z.string({ description: "Description (markdown)" }).max(
 var urlSchema = z.string().url();
 var docsUrlSchema = urlSchema.optional().or(z.literal("")).describe("Documentation site");
 var titleSchema = z.string({ description: "Descriptive name" }).max(MAX_TITLE_LENGTH);
+var scoreSchema = z.number({
+  description: "Value between 0 and 1"
+}).min(0).max(1);
 function metaSchema(options2) {
   const {
     descriptionDescription,
@@ -223,6 +226,8 @@ var issueSchema = z3.object(
 );
 
 // packages/models/src/lib/audit-output.ts
+var auditValueSchema = nonnegativeIntSchema.describe("Raw numeric value");
+var auditDisplayValueSchema = z4.string({ description: "Formatted value (e.g. '0.9 s', '2.1 MB')" }).optional();
 var auditDetailsSchema = z4.object(
   {
     issues: z4.array(issueSchema, { description: "List of findings" })
@@ -232,11 +237,9 @@ var auditDetailsSchema = z4.object(
 var auditOutputSchema = z4.object(
   {
     slug: slugSchema.describe("Reference to audit"),
-    displayValue: z4.string({ description: "Formatted value (e.g. '0.9 s', '2.1 MB')" }).optional(),
-    value: nonnegativeIntSchema.describe("Raw numeric value"),
-    score: z4.number({
-      description: "Value between 0 and 1"
-    }).min(0).max(1),
+    displayValue: auditDisplayValueSchema,
+    value: auditValueSchema,
+    score: scoreSchema,
     details: auditDetailsSchema.optional()
   },
   { description: "Audit information" }
@@ -375,28 +378,28 @@ var groupSchema = scorableSchema(
 var groupsSchema = z8.array(groupSchema, {
   description: "List of groups"
 }).optional().refine(
-  (groups) => !getDuplicateSlugsInGroups(groups),
-  (groups) => ({
-    message: duplicateSlugsInGroupsErrorMsg(groups)
+  (groups2) => !getDuplicateSlugsInGroups(groups2),
+  (groups2) => ({
+    message: duplicateSlugsInGroupsErrorMsg(groups2)
   })
 );
-function duplicateRefsInGroupsErrorMsg(groups) {
-  const duplicateRefs = getDuplicateRefsInGroups(groups);
+function duplicateRefsInGroupsErrorMsg(groups2) {
+  const duplicateRefs = getDuplicateRefsInGroups(groups2);
   return `In plugin groups the following references are not unique: ${errorItems(
     duplicateRefs
   )}`;
 }
-function getDuplicateRefsInGroups(groups) {
-  return hasDuplicateStrings(groups.map(({ slug: ref }) => ref).filter(exists));
+function getDuplicateRefsInGroups(groups2) {
+  return hasDuplicateStrings(groups2.map(({ slug: ref }) => ref).filter(exists));
 }
-function duplicateSlugsInGroupsErrorMsg(groups) {
-  const duplicateRefs = getDuplicateSlugsInGroups(groups);
+function duplicateSlugsInGroupsErrorMsg(groups2) {
+  const duplicateRefs = getDuplicateSlugsInGroups(groups2);
   return `In groups the following slugs are not unique: ${errorItems(
     duplicateRefs
   )}`;
 }
-function getDuplicateSlugsInGroups(groups) {
-  return Array.isArray(groups) ? hasDuplicateStrings(groups.map(({ slug }) => slug)) : false;
+function getDuplicateSlugsInGroups(groups2) {
+  return Array.isArray(groups2) ? hasDuplicateStrings(groups2.map(({ slug }) => slug)) : false;
 }
 
 // packages/models/src/lib/runner-config.ts
@@ -501,9 +504,9 @@ var CONFIG_FILE_NAME = "code-pushup.config";
 var SUPPORTED_CONFIG_FILE_FORMATS = ["ts", "mjs", "js"];
 
 // packages/models/src/lib/implementation/constants.ts
-var PERSIST_OUTPUT_DIR = ".code-pushup";
-var PERSIST_FORMAT = ["json"];
-var PERSIST_FILENAME = "report";
+var DEFAULT_PERSIST_OUTPUT_DIR = ".code-pushup";
+var DEFAULT_PERSIST_FILENAME = "report";
+var DEFAULT_PERSIST_FORMAT = ["json", "md"];
 
 // packages/models/src/lib/report.ts
 import { z as z13 } from "zod";
@@ -527,15 +530,15 @@ var pluginReportSchema = pluginMetaSchema.merge(
     )
   })
 );
-function missingRefsFromGroupsErrorMsg2(audits, groups) {
-  const missingRefs = getMissingRefsFromGroups2(audits, groups);
+function missingRefsFromGroupsErrorMsg2(audits, groups2) {
+  const missingRefs = getMissingRefsFromGroups2(audits, groups2);
   return `group references need to point to an existing audit in this plugin report: ${errorItems(
     missingRefs
   )}`;
 }
-function getMissingRefsFromGroups2(audits, groups) {
+function getMissingRefsFromGroups2(audits, groups2) {
   return hasMissingStrings(
-    groups.flatMap(
+    groups2.flatMap(
       ({ refs: auditRefs }) => auditRefs.map(({ slug: ref }) => ref)
     ),
     audits.map(({ slug }) => slug)
@@ -568,6 +571,138 @@ var reportSchema = packageVersionSchema({
   })
 );
 
+// packages/models/src/lib/reports-diff.ts
+import { z as z14 } from "zod";
+function makeComparisonSchema(schema) {
+  const sharedDescription = schema.description || "Result";
+  return z14.object({
+    before: schema.describe(`${sharedDescription} (source commit)`),
+    after: schema.describe(`${sharedDescription} (target commit)`)
+  });
+}
+function makeArraysComparisonSchema(diffSchema, resultSchema, description) {
+  return z14.object(
+    {
+      changed: z14.array(diffSchema),
+      unchanged: z14.array(resultSchema),
+      added: z14.array(resultSchema),
+      removed: z14.array(resultSchema)
+    },
+    { description }
+  );
+}
+var scorableMetaSchema = z14.object({ slug: slugSchema, title: titleSchema });
+var scorableWithPluginMetaSchema = scorableMetaSchema.merge(
+  z14.object({
+    plugin: pluginMetaSchema.pick({ slug: true, title: true }).describe("Plugin which defines it")
+  })
+);
+var scorableDiffSchema = scorableMetaSchema.merge(
+  z14.object({
+    scores: makeComparisonSchema(scoreSchema).merge(
+      z14.object({
+        diff: z14.number().min(-1).max(1).describe("Score change (`scores.after - scores.before`)")
+      })
+    ).describe("Score comparison")
+  })
+);
+var scorableWithPluginDiffSchema = scorableDiffSchema.merge(
+  scorableWithPluginMetaSchema
+);
+var categoryDiffSchema = scorableDiffSchema;
+var groupDiffSchema = scorableWithPluginDiffSchema;
+var auditDiffSchema = scorableWithPluginDiffSchema.merge(
+  z14.object({
+    values: makeComparisonSchema(auditValueSchema).merge(
+      z14.object({
+        diff: z14.number().int().describe("Value change (`values.after - values.before`)")
+      })
+    ).describe("Audit `value` comparison"),
+    displayValues: makeComparisonSchema(auditDisplayValueSchema).describe(
+      "Audit `displayValue` comparison"
+    )
+  })
+);
+var categoryResultSchema = scorableMetaSchema.merge(
+  z14.object({ score: scoreSchema })
+);
+var groupResultSchema = scorableWithPluginMetaSchema.merge(
+  z14.object({ score: scoreSchema })
+);
+var auditResultSchema = scorableWithPluginMetaSchema.merge(
+  auditOutputSchema.pick({ score: true, value: true, displayValue: true })
+);
+var reportsDiffSchema = z14.object({
+  commits: makeComparisonSchema(commitSchema).nullable().describe("Commits identifying compared reports"),
+  categories: makeArraysComparisonSchema(
+    categoryDiffSchema,
+    categoryResultSchema,
+    "Changes affecting categories"
+  ),
+  groups: makeArraysComparisonSchema(
+    groupDiffSchema,
+    groupResultSchema,
+    "Changes affecting groups"
+  ),
+  audits: makeArraysComparisonSchema(
+    auditDiffSchema,
+    auditResultSchema,
+    "Changes affecting audits"
+  )
+}).merge(
+  packageVersionSchema({
+    versionDescription: "NPM version of the CLI (when `compare` was run)",
+    required: true
+  })
+).merge(
+  executionMetaSchema({
+    descriptionDate: "Start date and time of the compare run",
+    descriptionDuration: "Duration of the compare run in ms"
+  })
+);
+
+// packages/utils/src/lib/diff.ts
+function matchArrayItemsByKey({
+  before,
+  after,
+  key
+}) {
+  const pairs = [];
+  const added = [];
+  const afterKeys = /* @__PURE__ */ new Set();
+  const keyFn = typeof key === "function" ? key : (item) => item[key];
+  for (const afterItem of after) {
+    const afterKey = keyFn(afterItem);
+    afterKeys.add(afterKey);
+    const match = before.find((beforeItem) => keyFn(beforeItem) === afterKey);
+    if (match) {
+      pairs.push({ before: match, after: afterItem });
+    } else {
+      added.push(afterItem);
+    }
+  }
+  const removed = before.filter(
+    (beforeItem) => !afterKeys.has(keyFn(beforeItem))
+  );
+  return {
+    pairs,
+    added,
+    removed
+  };
+}
+function comparePairs(pairs, equalsFn) {
+  return pairs.reduce(
+    (acc, pair) => ({
+      ...acc,
+      ...equalsFn(pair) ? { unchanged: [...acc.unchanged, pair.after] } : { changed: [...acc.changed, pair] }
+    }),
+    {
+      changed: [],
+      unchanged: []
+    }
+  );
+}
+
 // packages/utils/src/lib/execute-process.ts
 import { spawn } from "node:child_process";
 
@@ -576,13 +711,25 @@ import { join } from "node:path";
 
 // packages/utils/src/lib/file-system.ts
 import { bundleRequire } from "bundle-require";
-import chalk from "chalk";
+import chalk2 from "chalk";
 import { mkdir, readFile, readdir, rm, stat } from "node:fs/promises";
 
 // packages/utils/src/lib/formatting.ts
 function slugify(text) {
   return text.trim().toLowerCase().replace(/\s+|\//g, "-").replace(/[^a-z\d-]/g, "");
 }
+function pluralize(text, amount) {
+  if (amount != null && Math.abs(amount) === 1) {
+    return text;
+  }
+  if (text.endsWith("y")) {
+    return `${text.slice(0, -1)}ies`;
+  }
+  if (text.endsWith("s")) {
+    return `${text}es`;
+  }
+  return `${text}s`;
+}
 function formatBytes(bytes, decimals = 2) {
   const positiveBytes = Math.max(bytes, 0);
   if (positiveBytes === 0) {
@@ -594,6 +741,9 @@ function formatBytes(bytes, decimals = 2) {
   const i = Math.floor(Math.log(positiveBytes) / Math.log(k));
   return `${Number.parseFloat((positiveBytes / Math.pow(k, i)).toFixed(dm))} ${sizes[i]}`;
 }
+function pluralizeToken(token, times) {
+  return `${times} ${Math.abs(times) === 1 ? token : pluralize(token)}`;
+}
 function formatDuration(duration) {
   if (duration < 1e3) {
     return `${duration} ms`;
@@ -621,33 +771,106 @@ function isPromiseRejectedResult(result) {
   return result.status === "rejected";
 }
 
+// packages/utils/src/lib/logging.ts
+import isaacs_cliui from "@isaacs/cliui";
+import { cliui } from "@poppinss/cliui";
+import chalk from "chalk";
+
+// packages/utils/src/lib/reports/constants.ts
+var TERMINAL_WIDTH = 80;
+var NEW_LINE = "\n";
+var SCORE_COLOR_RANGE = {
+  GREEN_MIN: 0.9,
+  YELLOW_MIN: 0.5
+};
+var FOOTER_PREFIX = "Made with \u2764 by";
+var CODE_PUSHUP_DOMAIN = "code-pushup.dev";
+var README_LINK = "https://github.com/flowup/quality-metrics-cli#readme";
+var reportHeadlineText = "Code PushUp Report";
+var reportOverviewTableHeaders = [
+  "\u{1F3F7} Category",
+  "\u2B50 Score",
+  "\u{1F6E1} Audits"
+];
+var reportRawOverviewTableHeaders = ["Category", "Score", "Audits"];
+var reportMetaTableHeaders = [
+  "Commit",
+  "Version",
+  "Duration",
+  "Plugins",
+  "Categories",
+  "Audits"
+];
+var pluginMetaTableHeaders = [
+  "Plugin",
+  "Audits",
+  "Version",
+  "Duration"
+];
+var detailsTableHeaders = [
+  "Severity",
+  "Message",
+  "Source file",
+  "Line(s)"
+];
+
+// packages/utils/src/lib/logging.ts
+var singletonUiInstance;
+function ui() {
+  if (singletonUiInstance === void 0) {
+    singletonUiInstance = cliui();
+  }
+  return {
+    ...singletonUiInstance,
+    row: (args) => {
+      logListItem(args);
+    }
+  };
+}
+var singletonisaacUi;
+function logListItem(args) {
+  if (singletonisaacUi === void 0) {
+    singletonisaacUi = isaacs_cliui({ width: TERMINAL_WIDTH });
+  }
+  singletonisaacUi.div(...args);
+  const content = singletonisaacUi.toString();
+  singletonisaacUi.rows = [];
+  singletonUiInstance?.logger.log(content);
+}
+function link(text) {
+  return chalk.underline(chalk.blueBright(text));
+}
+
 // packages/utils/src/lib/log-results.ts
-function logMultipleResults(results, messagePrefix, succeededCallback, failedCallback) {
-  if (succeededCallback) {
+function logMultipleResults(results, messagePrefix, succeededTransform, failedTransform) {
+  if (succeededTransform) {
     const succeededResults = results.filter(isPromiseFulfilledResult);
     logPromiseResults(
       succeededResults,
       `${messagePrefix} successfully: `,
-      succeededCallback
+      succeededTransform
     );
   }
-  if (failedCallback) {
+  if (failedTransform) {
     const failedResults = results.filter(isPromiseRejectedResult);
     logPromiseResults(
       failedResults,
       `${messagePrefix} failed: `,
-      failedCallback
+      failedTransform
     );
   }
 }
-function logPromiseResults(results, logMessage, callback) {
+function logPromiseResults(results, logMessage, getMsg) {
   if (results.length > 0) {
-    if (results[0]?.status === "fulfilled") {
-      console.info(logMessage);
-    } else {
-      console.warn(logMessage);
-    }
-    results.forEach(callback);
+    const log2 = results[0]?.status === "fulfilled" ? (m) => {
+      ui().logger.success(m);
+    } : (m) => {
+      ui().logger.warning(m);
+    };
+    log2(logMessage);
+    results.forEach((result) => {
+      log2(getMsg(result));
+    });
   }
 }
 
@@ -681,26 +904,24 @@ async function ensureDirectoryExists(baseDir) {
     await mkdir(baseDir, { recursive: true });
     return;
   } catch (error) {
-    console.error(error.message);
+    ui().logger.error(error.message);
     if (error.code !== "EEXIST") {
       throw error;
     }
   }
 }
 function logMultipleFileResults(fileResults, messagePrefix) {
-  const succeededCallback = (result) => {
+  const succeededTransform = (result) => {
     const [fileName, size] = result.value;
-    const formattedSize = size ? ` (${chalk.gray(formatBytes(size))})` : "";
-    console.info(`- ${chalk.bold(fileName)}${formattedSize}`);
-  };
-  const failedCallback = (result) => {
-    console.warn(`- ${chalk.bold(result.reason)}`);
+    const formattedSize = size ? ` (${chalk2.gray(formatBytes(size))})` : "";
+    return `- ${chalk2.bold(fileName)}${formattedSize}`;
   };
+  const failedTransform = (result) => `- ${chalk2.bold(result.reason)}`;
   logMultipleResults(
     fileResults,
     messagePrefix,
-    succeededCallback,
-    failedCallback
+    succeededTransform,
+    failedTransform
   );
 }
 var NoExportError = class extends Error {
@@ -719,48 +940,105 @@ async function importEsmModule(options2) {
   return mod.default;
 }
 
-// packages/utils/src/lib/reports/constants.ts
-var TERMINAL_WIDTH = 80;
-var NEW_LINE = "\n";
-var SCORE_COLOR_RANGE = {
-  GREEN_MIN: 0.9,
-  YELLOW_MIN: 0.5
+// packages/utils/src/lib/reports/md/details.ts
+function details(title, content, cfg = { open: false }) {
+  return `<details${cfg.open ? " open" : ""}>
+<summary>${title}</summary>
+
+${content}
+
+</details>
+`;
+}
+
+// packages/utils/src/lib/reports/md/font-style.ts
+var stylesMap = {
+  i: "_",
+  // italic
+  b: "**",
+  // bold
+  s: "~",
+  // strike through
+  c: "`"
+  // code
 };
-var FOOTER_PREFIX = "Made with \u2764 by";
-var CODE_PUSHUP_DOMAIN = "code-pushup.dev";
-var README_LINK = "https://github.com/flowup/quality-metrics-cli#readme";
-var reportHeadlineText = "Code PushUp Report";
-var reportOverviewTableHeaders = [
-  "\u{1F3F7} Category",
-  "\u2B50 Score",
-  "\u{1F6E1} Audits"
-];
-var reportRawOverviewTableHeaders = ["Category", "Score", "Audits"];
-var reportMetaTableHeaders = [
-  "Commit",
-  "Version",
-  "Duration",
-  "Plugins",
-  "Categories",
-  "Audits"
-];
-var pluginMetaTableHeaders = [
-  "Plugin",
-  "Audits",
-  "Version",
-  "Duration"
-];
-var detailsTableHeaders = [
-  "Severity",
-  "Message",
-  "Source file",
-  "Line(s)"
-];
+function style(text, styles = ["b"]) {
+  return styles.reduce((t, s) => `${stylesMap[s]}${t}${stylesMap[s]}`, text);
+}
+
+// packages/utils/src/lib/reports/md/headline.ts
+function headline(text, hierarchy = 1) {
+  return `${"#".repeat(hierarchy)} ${text}`;
+}
+function h1(text) {
+  return headline(text, 1);
+}
+function h2(text) {
+  return headline(text, 2);
+}
+function h3(text) {
+  return headline(text, 3);
+}
+
+// packages/utils/src/lib/reports/md/image.ts
+function image(src, alt) {
+  return `![${alt}](${src})`;
+}
+
+// packages/utils/src/lib/reports/md/link.ts
+function link2(href, text) {
+  return `[${text || href}](${href})`;
+}
+
+// packages/utils/src/lib/reports/md/list.ts
+function li(text, order = "unordered") {
+  const style2 = order === "unordered" ? "-" : "- [ ]";
+  return `${style2} ${text}`;
+}
+
+// packages/utils/src/lib/reports/md/paragraphs.ts
+function paragraphs(...sections) {
+  return sections.filter(Boolean).join("\n\n");
+}
+
+// packages/utils/src/lib/reports/md/table.ts
+var alignString = /* @__PURE__ */ new Map([
+  ["l", ":--"],
+  ["c", ":--:"],
+  ["r", "--:"]
+]);
+function tableMd(data, align) {
+  if (data.length === 0) {
+    throw new Error("Data can't be empty");
+  }
+  const alignmentSetting = align ?? data[0]?.map(() => "c");
+  const tableContent = data.map((arr) => `|${arr.join("|")}|`);
+  const alignmentRow = `|${alignmentSetting?.map((s) => alignString.get(s)).join("|")}|`;
+  return tableContent[0] + NEW_LINE + alignmentRow + NEW_LINE + tableContent.slice(1).join(NEW_LINE);
+}
+function tableHtml(data) {
+  if (data.length === 0) {
+    throw new Error("Data can't be empty");
+  }
+  const tableContent = data.map((arr, index) => {
+    if (index === 0) {
+      const headerRow = arr.map((s) => `<th>${s}</th>`).join("");
+      return `<tr>${headerRow}</tr>`;
+    }
+    const row = arr.map((s) => `<td>${s}</td>`).join("");
+    return `<tr>${row}</tr>`;
+  });
+  return `<table>${tableContent.join("")}</table>`;
+}
 
 // packages/utils/src/lib/reports/utils.ts
 function formatReportScore(score) {
   return Math.round(score * 100).toString();
 }
+function formatScoreWithColor(score, options2) {
+  const styledNumber = options2?.skipBold ? formatReportScore(score) : style(formatReportScore(score));
+  return `${getRoundScoreMarker(score)} ${styledNumber}`;
+}
 function getRoundScoreMarker(score) {
   if (score >= SCORE_COLOR_RANGE.GREEN_MIN) {
     return "\u{1F7E2}";
@@ -779,6 +1057,30 @@ function getSquaredScoreMarker(score) {
   }
   return "\u{1F7E5}";
 }
+function getDiffMarker(diff) {
+  if (diff > 0) {
+    return "\u2191";
+  }
+  if (diff < 0) {
+    return "\u2193";
+  }
+  return "";
+}
+function colorByScoreDiff(text, diff) {
+  const color = diff > 0 ? "green" : diff < 0 ? "red" : "gray";
+  return shieldsBadge(text, color);
+}
+function shieldsBadge(text, color) {
+  return image(
+    `https://img.shields.io/badge/${encodeURIComponent(text)}-${color}`,
+    text
+  );
+}
+function formatDiffNumber(diff) {
+  const number = Math.abs(diff) === Number.POSITIVE_INFINITY ? "\u221E" : `${Math.abs(diff)}`;
+  const sign = diff < 0 ? "\u2212" : "+";
+  return `${sign}${number}`;
+}
 function getSeverityIcon(severity) {
   if (severity === "error") {
     return "\u{1F6A8}";
@@ -789,7 +1091,7 @@ function getSeverityIcon(severity) {
   return "\u2139\uFE0F";
 }
 function calcDuration(start, stop) {
-  return Math.floor((stop ?? performance.now()) - start);
+  return Math.round((stop ?? performance.now()) - start);
 }
 function countCategoryAudits(refs, plugins) {
   const groupLookup = plugins.reduce(
@@ -952,7 +1254,7 @@ var ProcessError = class extends Error {
   }
 };
 function executeProcess(cfg) {
-  const { observer, cwd, command, args } = cfg;
+  const { observer, cwd, command, args, alwaysResolve = false } = cfg;
   const { onStdout, onError, onComplete } = observer ?? {};
   const date = (/* @__PURE__ */ new Date()).toISOString();
   const start = performance.now();
@@ -972,7 +1274,7 @@ function executeProcess(cfg) {
     });
     process2.on("close", (code) => {
       const timings = { date, duration: calcDuration(start) };
-      if (code === 0) {
+      if (code === 0 || alwaysResolve) {
         onComplete?.();
         resolve({ code, stdout, stderr, ...timings });
       } else {
@@ -984,6 +1286,14 @@ function executeProcess(cfg) {
   });
 }
 
+// packages/utils/src/lib/filter.ts
+function filterItemRefsBy(items, refFilterFn) {
+  return items.map((item) => ({
+    ...item,
+    refs: item.refs.filter(refFilterFn)
+  })).filter((item) => item.refs.length);
+}
+
 // packages/utils/src/lib/git.ts
 import { isAbsolute, join as join2, relative } from "node:path";
 import { simpleGit } from "simple-git";
@@ -992,6 +1302,9 @@ import { simpleGit } from "simple-git";
 function toArray(val) {
   return Array.isArray(val) ? val : [val];
 }
+function objectToEntries(obj) {
+  return Object.entries(obj);
+}
 function deepClone(obj) {
   return obj == null || typeof obj !== "object" ? obj : structuredClone(obj);
 }
@@ -1001,14 +1314,14 @@ function toUnixPath(path) {
 
 // packages/utils/src/lib/git.ts
 async function getLatestCommit(git = simpleGit()) {
-  const log = await git.log({
+  const log2 = await git.log({
     maxCount: 1,
     format: { hash: "%H", message: "%s", author: "%an", date: "%aI" }
   });
-  if (!log.latest) {
+  if (!log2.latest) {
     return null;
   }
-  return commitSchema.parse(log.latest);
+  return commitSchema.parse(log2.latest);
 }
 function getGitRoot(git = simpleGit()) {
   return git.revparse("--show-toplevel");
@@ -1027,12 +1340,6 @@ function groupByStatus(results) {
   );
 }
 
-// packages/utils/src/lib/logging.ts
-import chalk2 from "chalk";
-function link(text) {
-  return chalk2.underline(chalk2.blueBright(text));
-}
-
 // packages/utils/src/lib/progress.ts
 import chalk3 from "chalk";
 import { MultiProgressBars } from "multi-progress-bars";
@@ -1088,80 +1395,16 @@ function getProgressBar(taskName) {
   };
 }
 
-// packages/utils/src/lib/reports/md/details.ts
-function details(title, content, cfg = { open: false }) {
-  return `<details${cfg.open ? " open" : ""}>
-<summary>${title}</summary>
-${content}
-</details>
-`;
-}
-
-// packages/utils/src/lib/reports/md/font-style.ts
-var stylesMap = {
-  i: "_",
-  // italic
-  b: "**",
-  // bold
-  s: "~",
-  // strike through
-  c: "`"
-  // code
-};
-function style(text, styles = ["b"]) {
-  return styles.reduce((t, s) => `${stylesMap[s]}${t}${stylesMap[s]}`, text);
-}
-
-// packages/utils/src/lib/reports/md/headline.ts
-function headline(text, hierarchy = 1) {
-  return `${"#".repeat(hierarchy)} ${text}`;
-}
-function h2(text) {
-  return headline(text, 2);
-}
-function h3(text) {
-  return headline(text, 3);
-}
-
-// packages/utils/src/lib/reports/md/link.ts
-function link2(href, text) {
-  return `[${text || href}](${href})`;
-}
-
-// packages/utils/src/lib/reports/md/list.ts
-function li(text, order = "unordered") {
-  const style2 = order === "unordered" ? "-" : "- [ ]";
-  return `${style2} ${text}`;
-}
-
-// packages/utils/src/lib/reports/md/table.ts
-var alignString = /* @__PURE__ */ new Map([
-  ["l", ":--"],
-  ["c", ":--:"],
-  ["r", "--:"]
-]);
-function tableMd(data, align) {
-  if (data.length === 0) {
-    throw new Error("Data can't be empty");
-  }
-  const alignmentSetting = align ?? data[0]?.map(() => "c");
-  const tableContent = data.map((arr) => `|${arr.join("|")}|`);
-  const alignmentRow = `|${alignmentSetting?.map((s) => alignString.get(s)).join("|")}|`;
-  return tableContent[0] + NEW_LINE + alignmentRow + NEW_LINE + tableContent.slice(1).join(NEW_LINE);
+// packages/utils/src/lib/reports/flatten-plugins.ts
+function listGroupsFromAllPlugins(report) {
+  return report.plugins.flatMap(
+    (plugin) => plugin.groups?.map((group) => ({ plugin, group })) ?? []
+  );
 }
-function tableHtml(data) {
-  if (data.length === 0) {
-    throw new Error("Data can't be empty");
-  }
-  const tableContent = data.map((arr, index) => {
-    if (index === 0) {
-      const headerRow = arr.map((s) => `<th>${s}</th>`).join("");
-      return `<tr>${headerRow}</tr>`;
-    }
-    const row = arr.map((s) => `<td>${s}</td>`).join("");
-    return `<tr>${row}</tr>`;
-  });
-  return `<table>${tableContent.join("")}</table>`;
+function listAuditsFromAllPlugins(report) {
+  return report.plugins.flatMap(
+    (plugin) => plugin.audits.map((audit) => ({ plugin, audit }))
+  );
 }
 
 // packages/utils/src/lib/reports/generate-md-report.ts
@@ -1327,54 +1570,285 @@ function reportToAboutSection(report) {
     h2("About") + NEW_LINE + NEW_LINE + `Report was created by [Code PushUp](${README_LINK}) on ${date}.` + NEW_LINE + NEW_LINE + tableMd(reportMetaTable, ["l", "c", "c", "c", "c", "c"]) + NEW_LINE + NEW_LINE + "The following plugins were run:" + NEW_LINE + NEW_LINE + tableMd(pluginMetaTable, ["l", "c", "c", "c"])
   );
 }
-function getDocsAndDescription({
-  docsUrl,
-  description
+function getDocsAndDescription({
+  docsUrl,
+  description
+}) {
+  if (docsUrl) {
+    const docsLink = link2(docsUrl, "\u{1F4D6} Docs");
+    if (!description) {
+      return docsLink + NEW_LINE + NEW_LINE;
+    }
+    if (description.endsWith("```")) {
+      return description + NEW_LINE + NEW_LINE + docsLink + NEW_LINE + NEW_LINE;
+    }
+    return `${description} ${docsLink}${NEW_LINE}${NEW_LINE}`;
+  }
+  if (description) {
+    return description + NEW_LINE + NEW_LINE;
+  }
+  return "";
+}
+function getAuditResult(audit, isHtml = false) {
+  const { displayValue, value } = audit;
+  return isHtml ? `<b>${displayValue || value}</b>` : style(String(displayValue || value));
+}
+
+// packages/utils/src/lib/reports/generate-md-reports-diff.ts
+var MAX_ROWS = 100;
+function generateMdReportsDiff(diff) {
+  return paragraphs(
+    formatDiffHeaderSection(diff),
+    formatDiffCategoriesSection(diff),
+    formatDiffGroupsSection(diff),
+    formatDiffAuditsSection(diff)
+  );
+}
+function formatDiffHeaderSection(diff) {
+  const outcomeTexts = {
+    positive: `\u{1F973} Code PushUp report has ${style("improved")}`,
+    negative: `\u{1F61F} Code PushUp report has ${style("regressed")}`,
+    mixed: `\u{1F928} Code PushUp report has both ${style(
+      "improvements and regressions"
+    )}`,
+    unchanged: `\u{1F610} Code PushUp report is ${style("unchanged")}`
+  };
+  const outcome = mergeDiffOutcomes(
+    changesToDiffOutcomes([
+      ...diff.categories.changed,
+      ...diff.groups.changed,
+      ...diff.audits.changed
+    ])
+  );
+  const styleCommit = (commit) => style(commit.hash.slice(0, 7), ["c"]);
+  const styleCommits = (commits) => {
+    const src = styleCommit(commits.before);
+    const tgt = styleCommit(commits.after);
+    return `compared target commit ${tgt} with source commit ${src}`;
+  };
+  return paragraphs(
+    h1("Code PushUp"),
+    diff.commits ? `${outcomeTexts[outcome]} \u2013 ${styleCommits(diff.commits)}.` : `${outcomeTexts[outcome]}.`
+  );
+}
+function formatDiffCategoriesSection(diff) {
+  const { changed, unchanged, added } = diff.categories;
+  const categoriesCount = changed.length + unchanged.length + added.length;
+  const hasChanges = unchanged.length < categoriesCount;
+  if (categoriesCount === 0) {
+    return "";
+  }
+  return paragraphs(
+    h2("\u{1F3F7}\uFE0F Categories"),
+    categoriesCount > 0 && tableMd(
+      [
+        [
+          "\u{1F3F7}\uFE0F Category",
+          hasChanges ? "\u2B50 Current score" : "\u2B50 Score",
+          "\u2B50 Previous score",
+          "\u{1F504} Score change"
+        ],
+        ...sortChanges(changed).map((category) => [
+          category.title,
+          formatScoreWithColor(category.scores.after),
+          formatScoreWithColor(category.scores.before, { skipBold: true }),
+          formatScoreChange(category.scores.diff)
+        ]),
+        ...added.map((category) => [
+          category.title,
+          formatScoreWithColor(category.score),
+          style("n/a (\\*)", ["i"]),
+          style("n/a (\\*)", ["i"])
+        ]),
+        ...unchanged.map((category) => [
+          category.title,
+          formatScoreWithColor(category.score),
+          formatScoreWithColor(category.score, { skipBold: true }),
+          "\u2013"
+        ])
+      ].map((row) => hasChanges ? row : row.slice(0, 2)),
+      hasChanges ? ["l", "c", "c", "c"] : ["l", "c"]
+    ),
+    added.length > 0 && style("(\\*) New category.", ["i"])
+  );
+}
+function formatDiffGroupsSection(diff) {
+  if (diff.groups.changed.length + diff.groups.unchanged.length === 0) {
+    return "";
+  }
+  return paragraphs(
+    h2("\u{1F397}\uFE0F Groups"),
+    formatGroupsOrAuditsDetails("group", diff.groups, {
+      headings: [
+        "\u{1F50C} Plugin",
+        "\u{1F5C3}\uFE0F Group",
+        "\u2B50 Current score",
+        "\u2B50 Previous score",
+        "\u{1F504} Score change"
+      ],
+      rows: sortChanges(diff.groups.changed).map((group) => [
+        group.plugin.title,
+        group.title,
+        formatScoreWithColor(group.scores.after),
+        formatScoreWithColor(group.scores.before, { skipBold: true }),
+        formatScoreChange(group.scores.diff)
+      ]),
+      align: ["l", "l", "c", "c", "c"]
+    })
+  );
+}
+function formatDiffAuditsSection(diff) {
+  return paragraphs(
+    h2("\u{1F6E1}\uFE0F Audits"),
+    formatGroupsOrAuditsDetails("audit", diff.audits, {
+      headings: [
+        "\u{1F50C} Plugin",
+        "\u{1F6E1}\uFE0F Audit",
+        "\u{1F4CF} Current value",
+        "\u{1F4CF} Previous value",
+        "\u{1F504} Value change"
+      ],
+      rows: sortChanges(diff.audits.changed).map((audit) => [
+        audit.plugin.title,
+        audit.title,
+        `${getSquaredScoreMarker(audit.scores.after)} ${style(
+          audit.displayValues.after || audit.values.after.toString()
+        )}`,
+        `${getSquaredScoreMarker(audit.scores.before)} ${audit.displayValues.before || audit.values.before.toString()}`,
+        formatValueChange(audit)
+      ]),
+      align: ["l", "l", "c", "c", "c"]
+    })
+  );
+}
+function formatGroupsOrAuditsDetails(token, { changed, unchanged }, table) {
+  return changed.length === 0 ? summarizeUnchanged(token, { changed, unchanged }) : details(
+    summarizeDiffOutcomes(changesToDiffOutcomes(changed), token),
+    paragraphs(
+      tableMd(
+        [table.headings, ...table.rows.slice(0, MAX_ROWS)],
+        table.align
+      ),
+      changed.length > MAX_ROWS && style(
+        `Only the ${MAX_ROWS} most affected ${pluralize(
+          token
+        )} are listed above for brevity.`,
+        ["i"]
+      ),
+      unchanged.length > 0 && summarizeUnchanged(token, { changed, unchanged })
+    )
+  );
+}
+function formatScoreChange(diff) {
+  const marker = getDiffMarker(diff);
+  const text = formatDiffNumber(Math.round(diff * 100));
+  return colorByScoreDiff(`${marker} ${text}`, diff);
+}
+function formatValueChange({
+  values,
+  scores
 }) {
-  if (docsUrl) {
-    const docsLink = link2(docsUrl, "\u{1F4D6} Docs");
-    if (!description) {
-      return docsLink + NEW_LINE + NEW_LINE;
+  const marker = getDiffMarker(values.diff);
+  const percentage = values.before === 0 ? values.diff > 0 ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY : Math.round(100 * values.diff / values.before);
+  const text = `${formatDiffNumber(percentage)}\u2009%`;
+  return colorByScoreDiff(`${marker} ${text}`, scores.diff);
+}
+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`;
     }
-    if (description.endsWith("```")) {
-      return description + NEW_LINE + NEW_LINE + docsLink + NEW_LINE + NEW_LINE;
+  }).join(", ");
+}
+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";
     }
-    return `${description} ${docsLink}${NEW_LINE}${NEW_LINE}`;
+    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 (description) {
-    return description + NEW_LINE + NEW_LINE;
+  if (outcomes.includes("positive") && !outcomes.includes("negative")) {
+    return "positive";
   }
-  return "";
+  if (outcomes.includes("negative") && !outcomes.includes("positive")) {
+    return "negative";
+  }
+  return "mixed";
 }
-function getAuditResult(audit, isHtml = false) {
-  const { displayValue, value } = audit;
-  return isHtml ? `<b>${displayValue || value}</b>` : style(String(displayValue || value));
+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/generate-stdout-summary.ts
-import cliui from "@isaacs/cliui";
+// packages/utils/src/lib/reports/log-stdout-summary.ts
 import chalk4 from "chalk";
-import CliTable3 from "cli-table3";
-function addLine(line = "") {
-  return line + NEW_LINE;
+function log(msg = "") {
+  ui().logger.log(msg);
 }
-function generateStdoutSummary(report) {
+function logStdoutSummary(report) {
   const printCategories = report.categories.length > 0;
-  return addLine(reportToHeaderSection2(report)) + addLine() + addLine(reportToDetailSection(report)) + (printCategories ? addLine(reportToOverviewSection2(report)) : "") + addLine(`${FOOTER_PREFIX} ${CODE_PUSHUP_DOMAIN}`);
+  log(reportToHeaderSection2(report));
+  log();
+  logPlugins(report);
+  if (printCategories) {
+    logCategories(report);
+  }
+  log(`${FOOTER_PREFIX} ${CODE_PUSHUP_DOMAIN}`);
+  log();
 }
 function reportToHeaderSection2(report) {
   const { packageName, version: version2 } = report;
   return `${chalk4.bold(reportHeadlineText)} - ${packageName}@${version2}`;
 }
-function reportToDetailSection(report) {
+function logPlugins(report) {
   const { plugins } = report;
-  return plugins.reduce((acc, plugin) => {
+  plugins.forEach((plugin) => {
     const { title, audits } = plugin;
-    const ui2 = cliui({ width: TERMINAL_WIDTH });
+    log();
+    log(chalk4.magentaBright.bold(`${title} audits`));
+    log();
     audits.forEach((audit) => {
-      ui2.div(
+      ui().row([
         {
-          text: withColor({ score: audit.score, text: "\u25CF" }),
+          text: applyScoreColor({ score: audit.score, text: "\u25CF" }),
           width: 2,
           padding: [0, 1, 0, 0]
         },
@@ -1388,34 +1862,40 @@ function reportToDetailSection(report) {
           width: 10,
           padding: [0, 0, 0, 0]
         }
-      );
+      ]);
     });
-    return acc + addLine() + addLine(chalk4.magentaBright.bold(`${title} audits`)) + addLine() + addLine(ui2.toString()) + addLine();
-  }, "");
-}
-function reportToOverviewSection2({
-  categories,
-  plugins
-}) {
-  const table = new CliTable3({
-    // eslint-disable-next-line no-magic-numbers
-    colWidths: [TERMINAL_WIDTH - 7 - 8 - 4, 7, 8],
-    head: reportRawOverviewTableHeaders,
-    colAligns: ["left", "right", "right"],
-    style: {
-      head: ["cyan"]
-    }
+    log();
   });
-  table.push(
-    ...categories.map(({ title, score, refs }) => [
-      title,
-      withColor({ score }),
-      countCategoryAudits(refs, plugins)
-    ])
+}
+function logCategories({ categories, plugins }) {
+  const hAlign = (idx) => idx === 0 ? "left" : "right";
+  const rows = categories.map(({ title, score, refs }) => [
+    title,
+    applyScoreColor({ score }),
+    countCategoryAudits(refs, plugins)
+  ]);
+  const table = ui().table();
+  table.columnWidths([TERMINAL_WIDTH - 9 - 10 - 4, 9, 10]);
+  table.head(
+    reportRawOverviewTableHeaders.map((heading, idx) => ({
+      content: chalk4.cyan(heading),
+      hAlign: hAlign(idx)
+    }))
+  );
+  rows.forEach(
+    (row) => table.row(
+      row.map((content, idx) => ({
+        content: content.toString(),
+        hAlign: hAlign(idx)
+      }))
+    )
   );
-  return addLine(chalk4.magentaBright.bold("Categories")) + addLine() + addLine(table.toString());
+  log(chalk4.magentaBright.bold("Categories"));
+  log();
+  table.render();
+  log();
 }
-function withColor({ score, text }) {
+function applyScoreColor({ score, text }) {
   const formattedScore = text ?? formatReportScore(score);
   const style2 = text ? chalk4 : chalk4.bold;
   if (score >= SCORE_COLOR_RANGE.GREEN_MIN) {
@@ -1438,7 +1918,7 @@ var GroupRefInvalidError = class extends Error {
 function scoreReport(report) {
   const allScoredAuditsAndGroups = /* @__PURE__ */ new Map();
   const scoredPlugins = report.plugins.map((plugin) => {
-    const { groups, ...pluginProps } = plugin;
+    const { groups: groups2, ...pluginProps } = plugin;
     plugin.audits.forEach((audit) => {
       allScoredAuditsAndGroups.set(`${plugin.slug}-${audit.slug}-audit`, audit);
     });
@@ -1451,7 +1931,7 @@ function scoreReport(report) {
       }
       return score;
     }
-    const scoredGroups = groups?.map((group) => ({
+    const scoredGroups = groups2?.map((group) => ({
       ...group,
       score: calculateScore(group.refs, groupScoreFn)
     })) ?? [];
@@ -1518,7 +1998,7 @@ function parseScoringParameters(refs, scoreFn) {
 function sortReport(report) {
   const { categories, plugins } = report;
   const sortedCategories = categories.map((category) => {
-    const { audits, groups } = category.refs.reduce(
+    const { audits, groups: groups2 } = category.refs.reduce(
       (acc, ref) => ({
         ...acc,
         ...ref.type === "group" ? {
@@ -1529,7 +2009,7 @@ function sortReport(report) {
       }),
       { groups: [], audits: [] }
     );
-    const sortedAuditsAndGroups = [...audits, ...groups].sort(
+    const sortedAuditsAndGroups = [...audits, ...groups2].sort(
       compareCategoryAuditsAndGroups
     );
     const sortedRefs = [...category.refs].sort((a, b) => {
@@ -1566,9 +2046,9 @@ function sortPlugins(plugins) {
 
 // packages/utils/src/lib/verbose-utils.ts
 function getLogVerbose(verbose = false) {
-  return (...args) => {
+  return (msg) => {
     if (verbose) {
-      console.info(...args);
+      ui().logger.info(msg);
     }
   };
 }
@@ -1586,7 +2066,7 @@ var verboseUtils = (verbose = false) => ({
 
 // packages/core/package.json
 var name = "@code-pushup/core";
-var version = "0.26.1";
+var version = "0.28.0";
 
 // packages/core/src/lib/implementation/execute-plugin.ts
 import chalk5 from "chalk";
@@ -1656,7 +2136,7 @@ async function executePlugin(pluginConfig, onProgress) {
     audits: pluginConfigAudits,
     description,
     docsUrl,
-    groups,
+    groups: groups2,
     ...pluginMeta
   } = pluginConfig;
   const runnerResult = typeof runner === "object" ? await executeRunnerConfig(runner, onProgress) : await executeRunnerFunction(runner, onProgress);
@@ -1678,7 +2158,7 @@ async function executePlugin(pluginConfig, onProgress) {
     audits: auditReports,
     ...description && { description },
     ...docsUrl && { docsUrl },
-    ...groups && { groups }
+    ...groups2 && { groups: groups2 }
   };
 }
 async function executePlugins(plugins, options2) {
@@ -1699,11 +2179,9 @@ async function executePlugins(plugins, options2) {
     }
   }, Promise.resolve([]));
   progressBar?.endProgress("Done running plugins");
-  const errorsCallback = ({ reason }) => {
-    console.error(reason);
-  };
+  const errorsTransform = ({ reason }) => String(reason);
   const results = await Promise.allSettled(pluginsResult);
-  logMultipleResults(results, "Plugins", void 0, errorsCallback);
+  logMultipleResults(results, "Plugins", void 0, errorsTransform);
   const { fulfilled, rejected } = groupByStatus(results);
   if (rejected.length > 0) {
     const errorMessages = rejected.map(({ reason }) => String(reason)).join(", ");
@@ -1758,7 +2236,7 @@ var PersistError = class extends Error {
 async function persistReport(report, options2) {
   const { outputDir, filename, format } = options2;
   const sortedScoredReport = sortReport(scoreReport(report));
-  console.info(generateStdoutSummary(sortedScoredReport));
+  logStdoutSummary(sortedScoredReport);
   const results = format.map((reportType) => {
     switch (reportType) {
       case "json":
@@ -1777,7 +2255,7 @@ async function persistReport(report, options2) {
     try {
       await mkdir2(outputDir, { recursive: true });
     } catch (error) {
-      console.warn(error);
+      ui().logger.warning(error.toString());
       throw new PersistDirError(outputDir);
     }
   }
@@ -1792,7 +2270,7 @@ async function persistReport(report, options2) {
 }
 async function persistResult(reportPath, content) {
   return writeFile(reportPath, content).then(() => stat2(reportPath)).then((stats) => [reportPath, stats.size]).catch((error) => {
-    console.warn(error);
+    ui().logger.warning(error.toString());
     throw new PersistError(reportPath);
   });
 }
@@ -1813,8 +2291,209 @@ async function collectAndPersistReports(options2) {
   });
 }
 
-// packages/core/src/lib/implementation/read-rc-file.ts
+// packages/core/src/lib/compare.ts
+import { writeFile as writeFile2 } from "node:fs/promises";
 import { join as join5 } from "node:path";
+
+// packages/core/src/lib/implementation/compare-scorables.ts
+function compareCategories(reports) {
+  const { pairs, added, removed } = matchArrayItemsByKey({
+    before: reports.before.categories,
+    after: reports.after.categories,
+    key: "slug"
+  });
+  const { changed, unchanged } = comparePairs(
+    pairs,
+    ({ before, after }) => before.score === after.score
+  );
+  return {
+    changed: changed.map(categoryPairToDiff),
+    unchanged: unchanged.map(categoryToResult),
+    added: added.map(categoryToResult),
+    removed: removed.map(categoryToResult)
+  };
+}
+function compareGroups(reports) {
+  const { pairs, added, removed } = matchArrayItemsByKey({
+    before: listGroupsFromAllPlugins(reports.before),
+    after: listGroupsFromAllPlugins(reports.after),
+    key: ({ plugin, group }) => `${plugin.slug}/${group.slug}`
+  });
+  const { changed, unchanged } = comparePairs(
+    pairs,
+    ({ before, after }) => before.group.score === after.group.score
+  );
+  return {
+    changed: changed.map(pluginGroupPairToDiff),
+    unchanged: unchanged.map(pluginGroupToResult),
+    added: added.map(pluginGroupToResult),
+    removed: removed.map(pluginGroupToResult)
+  };
+}
+function compareAudits2(reports) {
+  const { pairs, added, removed } = matchArrayItemsByKey({
+    before: listAuditsFromAllPlugins(reports.before),
+    after: listAuditsFromAllPlugins(reports.after),
+    key: ({ plugin, audit }) => `${plugin.slug}/${audit.slug}`
+  });
+  const { changed, unchanged } = comparePairs(
+    pairs,
+    ({ before, after }) => before.audit.value === after.audit.value && before.audit.score === after.audit.score
+  );
+  return {
+    changed: changed.map(pluginAuditPairToDiff),
+    unchanged: unchanged.map(pluginAuditToResult),
+    added: added.map(pluginAuditToResult),
+    removed: removed.map(pluginAuditToResult)
+  };
+}
+function categoryToResult(category) {
+  return {
+    slug: category.slug,
+    title: category.title,
+    score: category.score
+  };
+}
+function categoryPairToDiff({
+  before,
+  after
+}) {
+  return {
+    slug: after.slug,
+    title: after.title,
+    scores: {
+      before: before.score,
+      after: after.score,
+      diff: after.score - before.score
+    }
+  };
+}
+function pluginGroupToResult({ group, plugin }) {
+  return {
+    slug: group.slug,
+    title: group.title,
+    plugin: {
+      slug: plugin.slug,
+      title: plugin.title
+    },
+    score: group.score
+  };
+}
+function pluginGroupPairToDiff({
+  before,
+  after
+}) {
+  return {
+    slug: after.group.slug,
+    title: after.group.title,
+    plugin: {
+      slug: after.plugin.slug,
+      title: after.plugin.title
+    },
+    scores: {
+      before: before.group.score,
+      after: after.group.score,
+      diff: after.group.score - before.group.score
+    }
+  };
+}
+function pluginAuditToResult({ audit, plugin }) {
+  return {
+    slug: audit.slug,
+    title: audit.title,
+    plugin: {
+      slug: plugin.slug,
+      title: plugin.title
+    },
+    score: audit.score,
+    value: audit.value,
+    displayValue: audit.displayValue
+  };
+}
+function pluginAuditPairToDiff({
+  before,
+  after
+}) {
+  return {
+    slug: after.audit.slug,
+    title: after.audit.title,
+    plugin: {
+      slug: after.plugin.slug,
+      title: after.plugin.title
+    },
+    scores: {
+      before: before.audit.score,
+      after: after.audit.score,
+      diff: after.audit.score - before.audit.score
+    },
+    values: {
+      before: before.audit.value,
+      after: after.audit.value,
+      diff: after.audit.value - before.audit.value
+    },
+    displayValues: {
+      before: before.audit.displayValue,
+      after: after.audit.displayValue
+    }
+  };
+}
+
+// packages/core/src/lib/compare.ts
+async function compareReportFiles(inputPaths, persistConfig) {
+  const { outputDir, filename, format } = persistConfig;
+  const [reportBefore, reportAfter] = await Promise.all([
+    readJsonFile(inputPaths.before),
+    readJsonFile(inputPaths.after)
+  ]);
+  const reports = {
+    before: reportSchema.parse(reportBefore),
+    after: reportSchema.parse(reportAfter)
+  };
+  const reportsDiff = compareReports(reports);
+  return Promise.all(
+    format.map(async (fmt) => {
+      const outputPath = join5(outputDir, `${filename}-diff.${fmt}`);
+      const content = reportsDiffToFileContent(reportsDiff, fmt);
+      await ensureDirectoryExists(outputDir);
+      await writeFile2(outputPath, content);
+      return outputPath;
+    })
+  );
+}
+function compareReports(reports) {
+  const start = performance.now();
+  const date = (/* @__PURE__ */ new Date()).toISOString();
+  const commits = reports.before.commit != null && reports.after.commit != null ? { before: reports.before.commit, after: reports.after.commit } : null;
+  const scoredReports = {
+    before: scoreReport(reports.before),
+    after: scoreReport(reports.after)
+  };
+  const categories = compareCategories(scoredReports);
+  const groups2 = compareGroups(scoredReports);
+  const audits = compareAudits2(scoredReports);
+  const duration = calcDuration(start);
+  return {
+    commits,
+    categories,
+    groups: groups2,
+    audits,
+    packageName: name,
+    version,
+    date,
+    duration
+  };
+}
+function reportsDiffToFileContent(reportsDiff, format) {
+  switch (format) {
+    case "json":
+      return JSON.stringify(reportsDiff, null, 2);
+    case "md":
+      return generateMdReportsDiff(reportsDiff);
+  }
+}
+
+// packages/core/src/lib/implementation/read-rc-file.ts
+import { join as join6 } from "node:path";
 var ConfigPathError = class extends Error {
   constructor(configPath) {
     super(`Provided path '${configPath}' is not valid.`);
@@ -1848,7 +2527,7 @@ async function autoloadRc(tsconfig) {
     );
   }
   return readRcByPath(
-    join5(process.cwd(), `${CONFIG_FILE_NAME}.${ext}`),
+    join6(process.cwd(), `${CONFIG_FILE_NAME}.${ext}`),
     tsconfig
   );
 }
@@ -1986,15 +2665,7 @@ var CLI_NAME = "Code PushUp CLI";
 var CLI_SCRIPT_NAME = "code-pushup";
 
 // packages/cli/src/lib/implementation/logging.ts
-import { cliui as cliui2 } from "@poppinss/cliui";
 import chalk6 from "chalk";
-var singletonUiInstance;
-function ui() {
-  if (singletonUiInstance === void 0) {
-    singletonUiInstance = cliui2();
-  }
-  return singletonUiInstance;
-}
 function renderConfigureCategoriesHint() {
   ui().logger.info(
     chalk6.gray(
@@ -2031,51 +2702,12 @@ function renderIntegratePortalHint() {
   ).render();
 }
 
-// packages/cli/src/lib/implementation/global.utils.ts
-function filterKebabCaseKeys(obj) {
-  return Object.entries(obj).filter(([key]) => !key.includes("-")).reduce(
-    (acc, [key, value]) => typeof value === "string" || typeof value === "object" && Array.isArray(obj[key]) ? { ...acc, [key]: value } : typeof value === "object" && !Array.isArray(value) && value != null ? {
-      ...acc,
-      [key]: filterKebabCaseKeys(value)
-    } : { ...acc, [key]: value },
-    {}
-  );
-}
-function logErrorBeforeThrow(fn) {
-  return async (...args) => {
-    try {
-      return await fn(...args);
-    } catch (error) {
-      console.error(error);
-      await new Promise((resolve) => process.stdout.write("", resolve));
-      throw error;
-    }
-  };
-}
-function coerceArray(param) {
-  return [...new Set(toArray(param).flatMap((f) => f.split(",")))];
-}
-
-// packages/cli/src/lib/implementation/only-plugins.options.ts
-var onlyPluginsOption = {
-  describe: "List of plugins to run. If not set all plugins are run.",
-  type: "array",
-  default: [],
-  coerce: coerceArray
-};
-function yargsOnlyPluginsOptionsDefinition() {
-  return {
-    onlyPlugins: onlyPluginsOption
-  };
-}
-
 // packages/cli/src/lib/autorun/autorun-command.ts
 function yargsAutorunCommandObject() {
   const command = "autorun";
   return {
     command,
     describe: "Shortcut for running collect followed by upload",
-    builder: yargsOnlyPluginsOptionsDefinition(),
     handler: async (args) => {
       ui().logger.log(chalk7.bold(CLI_NAME));
       ui().logger.info(chalk7.gray(`Run ${command}...`));
@@ -2112,7 +2744,6 @@ function yargsCollectCommandObject() {
   return {
     command,
     describe: "Run Plugins and collect results",
-    builder: yargsOnlyPluginsOptionsDefinition(),
     handler: async (args) => {
       const options2 = args;
       ui().logger.log(chalk8.bold(CLI_NAME));
@@ -2149,15 +2780,76 @@ function renderUploadAutorunHint() {
   ).render();
 }
 
+// packages/cli/src/lib/compare/compare-command.ts
+import chalk9 from "chalk";
+
+// packages/cli/src/lib/implementation/compare.options.ts
+function yargsCompareOptionsDefinition() {
+  return {
+    before: {
+      describe: "Path to source report.json",
+      type: "string",
+      demandOption: true
+    },
+    after: {
+      describe: "Path to target report.json",
+      type: "string",
+      demandOption: true
+    }
+  };
+}
+
+// packages/cli/src/lib/compare/compare-command.ts
+function yargsCompareCommandObject() {
+  const command = "compare";
+  return {
+    command,
+    describe: "Compare 2 report files and create a diff file",
+    builder: yargsCompareOptionsDefinition(),
+    handler: async (args) => {
+      ui().logger.log(chalk9.bold(CLI_NAME));
+      ui().logger.info(chalk9.gray(`Run ${command}...`));
+      const options2 = args;
+      const { before, after, persist } = options2;
+      const outputPaths = await compareReportFiles({ before, after }, persist);
+      ui().logger.info(
+        `Reports diff written to ${outputPaths.map((path) => chalk9.bold(path)).join(" and ")}`
+      );
+    }
+  };
+}
+
+// packages/cli/src/lib/implementation/global.utils.ts
+function filterKebabCaseKeys(obj) {
+  return Object.entries(obj).filter(([key]) => !key.includes("-")).reduce(
+    (acc, [key, value]) => typeof value === "string" || typeof value === "object" && Array.isArray(obj[key]) ? { ...acc, [key]: value } : typeof value === "object" && !Array.isArray(value) && value != null ? {
+      ...acc,
+      [key]: filterKebabCaseKeys(value)
+    } : { ...acc, [key]: value },
+    {}
+  );
+}
+function logErrorBeforeThrow(fn) {
+  return async (...args) => {
+    try {
+      return await fn(...args);
+    } catch (error) {
+      console.error(error);
+      await new Promise((resolve) => process.stdout.write("", resolve));
+      throw error;
+    }
+  };
+}
+function coerceArray(param) {
+  return [...new Set(toArray(param).flatMap((f) => f.split(",")))];
+}
+
 // packages/cli/src/lib/print-config/print-config-command.ts
 function yargsConfigCommandObject() {
   const command = "print-config";
   return {
     command,
     describe: "Print config",
-    builder: {
-      onlyPlugins: onlyPluginsOption
-    },
     handler: (yargsArgs) => {
       const { _, $0, ...args } = yargsArgs;
       const cleanArgs = filterKebabCaseKeys(args);
@@ -2167,15 +2859,15 @@ function yargsConfigCommandObject() {
 }
 
 // packages/cli/src/lib/upload/upload-command.ts
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 function yargsUploadCommandObject() {
   const command = "upload";
   return {
     command,
     describe: "Upload report results to the portal",
     handler: async (args) => {
-      ui().logger.log(chalk9.bold(CLI_NAME));
-      ui().logger.info(chalk9.gray(`Run ${command}...`));
+      ui().logger.log(chalk10.bold(CLI_NAME));
+      ui().logger.info(chalk10.gray(`Run ${command}...`));
       const options2 = args;
       if (options2.upload == null) {
         renderIntegratePortalHint();
@@ -2196,6 +2888,7 @@ var commands = [
   yargsAutorunCommandObject(),
   yargsCollectCommandObject(),
   yargsUploadCommandObject(),
+  yargsCompareCommandObject(),
   yargsConfigCommandObject()
 ];
 
@@ -2222,9 +2915,9 @@ async function coreConfigMiddleware(processArgs) {
   return {
     ...config != null && { config },
     persist: {
-      outputDir: cliPersist?.outputDir ?? rcPersist?.outputDir ?? PERSIST_OUTPUT_DIR,
-      format: cliPersist?.format ?? rcPersist?.format ?? PERSIST_FORMAT,
-      filename: cliPersist?.filename ?? rcPersist?.filename ?? PERSIST_FILENAME
+      outputDir: cliPersist?.outputDir ?? rcPersist?.outputDir ?? DEFAULT_PERSIST_OUTPUT_DIR,
+      filename: cliPersist?.filename ?? rcPersist?.filename ?? DEFAULT_PERSIST_FILENAME,
+      format: cliPersist?.format ?? rcPersist?.format ?? DEFAULT_PERSIST_FORMAT
     },
     ...upload2 != null && { upload: upload2 },
     categories: rcCategories ?? [],
@@ -2234,58 +2927,64 @@ async function coreConfigMiddleware(processArgs) {
 }
 
 // packages/cli/src/lib/implementation/only-plugins.utils.ts
-import chalk10 from "chalk";
-function filterPluginsBySlug(plugins, { onlyPlugins }) {
-  if (!onlyPlugins?.length) {
-    return plugins;
-  }
-  return plugins.filter((plugin) => onlyPlugins.includes(plugin.slug));
-}
-function filterCategoryByPluginSlug(categories, {
-  onlyPlugins,
+import chalk11 from "chalk";
+function validateOnlyPluginsOption({
+  plugins,
+  categories
+}, {
+  onlyPlugins = [],
   verbose = false
-}) {
-  if (categories.length === 0) {
-    return categories;
-  }
-  if (!onlyPlugins?.length) {
-    return categories;
-  }
-  return categories.filter(
-    (category) => category.refs.every((ref) => {
-      const isNotSkipped = onlyPlugins.includes(ref.plugin);
-      if (!isNotSkipped && verbose) {
-        console.info(
-          `${chalk10.yellow("\u26A0")} Category "${category.title}" is ignored because it references audits from skipped plugin "${ref.plugin}"`
-        );
-      }
-      return isNotSkipped;
-    })
+} = {}) {
+  const onlyPluginsSet = new Set(onlyPlugins);
+  const missingPlugins = onlyPlugins.filter(
+    (plugin) => !plugins.some(({ slug }) => slug === plugin)
   );
-}
-function validateOnlyPluginsOption(plugins, {
-  onlyPlugins,
-  verbose = false
-}) {
-  const missingPlugins = onlyPlugins?.length ? onlyPlugins.filter((plugin) => !plugins.some(({ slug }) => slug === plugin)) : [];
   if (missingPlugins.length > 0 && verbose) {
-    console.warn(
-      `${chalk10.yellow(
+    ui().logger.info(
+      `${chalk11.yellow(
         "\u26A0"
       )} The --onlyPlugin argument references plugins with "${missingPlugins.join(
         '", "'
       )}" slugs, but no such plugins are present in the configuration. Expected one of the following plugin slugs: "${plugins.map(({ slug }) => slug).join('", "')}".`
     );
   }
+  if (categories.length > 0) {
+    const removedCategorieSlugs = filterItemRefsBy(
+      categories,
+      ({ plugin }) => !onlyPluginsSet.has(plugin)
+    ).map(({ slug }) => slug);
+    ui().logger.info(
+      `The --onlyPlugin argument removed categories with "${removedCategorieSlugs.join(
+        '", "'
+      )}" slugs.
+    `
+    );
+  }
 }
 
 // packages/cli/src/lib/implementation/only-plugins.middleware.ts
-function onlyPluginsMiddleware(processArgs) {
-  validateOnlyPluginsOption(processArgs.plugins, processArgs);
+function onlyPluginsMiddleware(originalProcessArgs) {
+  const { categories = [], onlyPlugins: originalOnlyPlugins } = originalProcessArgs;
+  if (originalOnlyPlugins && originalOnlyPlugins.length > 0) {
+    const { verbose, plugins, onlyPlugins } = originalProcessArgs;
+    validateOnlyPluginsOption(
+      { plugins, categories },
+      { onlyPlugins, verbose }
+    );
+    const onlyPluginsSet = new Set(onlyPlugins);
+    return {
+      ...originalProcessArgs,
+      plugins: plugins.filter(({ slug }) => onlyPluginsSet.has(slug)),
+      categories: filterItemRefsBy(
+        categories,
+        ({ plugin }) => onlyPluginsSet.has(plugin)
+      )
+    };
+  }
   return {
-    ...processArgs,
-    plugins: filterPluginsBySlug(processArgs.plugins, processArgs),
-    categories: filterCategoryByPluginSlug(processArgs.categories, processArgs)
+    ...originalProcessArgs,
+    // if undefined fill categories with empty array
+    categories
   };
 }
 
@@ -2369,20 +3068,44 @@ function yargsGlobalOptionsDefinition() {
   };
 }
 
+// packages/cli/src/lib/implementation/only-plugins.options.ts
+var onlyPluginsOption = {
+  describe: "List of plugins to run. If not set all plugins are run.",
+  type: "array",
+  default: [],
+  coerce: coerceArray
+};
+function yargsOnlyPluginsOptionsDefinition() {
+  return {
+    onlyPlugins: onlyPluginsOption
+  };
+}
+
 // packages/cli/src/lib/options.ts
 var options = {
   ...yargsGlobalOptionsDefinition(),
-  ...yargsCoreConfigOptionsDefinition()
+  ...yargsCoreConfigOptionsDefinition(),
+  ...yargsOnlyPluginsOptionsDefinition()
+};
+var groups = {
+  "Global Options:": [
+    ...Object.keys(yargsGlobalOptionsDefinition()),
+    ...Object.keys(yargsOnlyPluginsOptionsDefinition())
+  ],
+  "Persist Options:": Object.keys(yargsPersistConfigOptionsDefinition()),
+  "Upload Options:": Object.keys(yargsUploadConfigOptionsDefinition())
 };
 
 // packages/cli/src/lib/yargs-cli.ts
-import chalk11 from "chalk";
+import chalk12 from "chalk";
 import yargs from "yargs";
 function yargsCli(argv, cfg) {
   const { usageMessage, scriptName, noExitProcess } = cfg;
   const commands2 = cfg.commands ?? [];
   const middlewares2 = cfg.middlewares ?? [];
   const options2 = cfg.options ?? {};
+  const groups2 = cfg.groups ?? {};
+  const examples = cfg.examples ?? [];
   const cli2 = yargs(argv);
   cli2.help().version(false).alias("h", "help").check((args) => {
     const persist = args["persist"];
@@ -2394,11 +3117,17 @@ function yargsCli(argv, cfg) {
     (config) => Array.isArray(config) ? config.at(-1) : config
   ).options(options2).wrap(TERMINAL_WIDTH);
   if (usageMessage) {
-    cli2.usage(chalk11.bold(usageMessage));
+    cli2.usage(chalk12.bold(usageMessage));
   }
   if (scriptName) {
     cli2.scriptName(scriptName);
   }
+  examples.forEach(
+    ([exampleName, description]) => cli2.example(exampleName, description)
+  );
+  Object.entries(groups2).forEach(
+    ([groupName, optionNames]) => cli2.group(optionNames, groupName)
+  );
   middlewares2.forEach(({ middlewareFunction, applyBeforeValidation }) => {
     cli2.middleware(
       logErrorBeforeThrow(middlewareFunction),
@@ -2439,6 +3168,29 @@ var cli = (args) => yargsCli(args, {
   usageMessage: CLI_NAME,
   scriptName: CLI_SCRIPT_NAME,
   options,
+  groups,
+  examples: [
+    [
+      "code-pushup",
+      "Run collect followed by upload based on configuration from code-pushup.config.* file."
+    ],
+    [
+      "code-pushup collect --tsconfig=tsconfig.base.json",
+      "Run collect using custom tsconfig to parse code-pushup.config.ts file."
+    ],
+    [
+      "code-pushup collect --onlyPlugins=coverage",
+      "Run collect with only coverage plugin, other plugins from config file will be skipped."
+    ],
+    [
+      "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 print-config --config code-pushup.config.test.js",
+      "Print resolved config object parsed from custom config location"
+    ]
+  ],
   middlewares,
   commands
 });