@code-pushup/cli 0.48.0 → 0.50.0

package/index.js

@@ -4,7 +4,7 @@
 import { hideBin } from "yargs/helpers";
 
 // packages/cli/src/lib/autorun/autorun-command.ts
-import chalk7 from "chalk";
+import { bold as bold7, gray as gray4 } from "ansis";
 
 // packages/models/src/lib/implementation/schemas.ts
 import { MATERIAL_ICONS } from "vscode-material-icons";
@@ -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,15 +754,286 @@ 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";
+import { md } from "build-md";
+
+// packages/utils/src/lib/reports/constants.ts
+var TERMINAL_WIDTH = 80;
+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/code-pushup/cli#readme";
+var REPORT_HEADLINE_TEXT = "Code PushUp Report";
+var REPORT_RAW_OVERVIEW_TABLE_HEADERS = [
+  "Category",
+  "Score",
+  "Audits"
+];
 
 // packages/utils/src/lib/reports/utils.ts
-import { join } from "node:path";
+function formatReportScore(score) {
+  const scaledScore = score * 100;
+  const roundedScore = Math.round(scaledScore);
+  return roundedScore === 100 && score !== 1 ? Math.floor(scaledScore).toString() : roundedScore.toString();
+}
+function formatScoreWithColor(score, options2) {
+  const styledNumber = options2?.skipBold ? formatReportScore(score) : md.bold(formatReportScore(score));
+  return md`${scoreMarker(score)} ${styledNumber}`;
+}
+var MARKERS = {
+  circle: {
+    red: "\u{1F534}",
+    yellow: "\u{1F7E1}",
+    green: "\u{1F7E2}"
+  },
+  square: {
+    red: "\u{1F7E5}",
+    yellow: "\u{1F7E8}",
+    green: "\u{1F7E9}"
+  }
+};
+function scoreMarker(score, markerType = "circle") {
+  if (score >= SCORE_COLOR_RANGE.GREEN_MIN) {
+    return MARKERS[markerType].green;
+  }
+  if (score >= SCORE_COLOR_RANGE.YELLOW_MIN) {
+    return MARKERS[markerType].yellow;
+  }
+  return MARKERS[markerType].red;
+}
+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 md.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 severityMarker(severity) {
+  if (severity === "error") {
+    return "\u{1F6A8}";
+  }
+  if (severity === "warning") {
+    return "\u26A0\uFE0F";
+  }
+  return "\u2139\uFE0F";
+}
+function formatScoreChange(diff) {
+  const marker = getDiffMarker(diff);
+  const text = formatDiffNumber(Math.round(diff * 1e3) / 10);
+  return colorByScoreDiff(`${marker} ${text}`, diff);
+}
+function formatValueChange({
+  values,
+  scores
+}) {
+  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 calcDuration(start, stop) {
+  return Math.round((stop ?? performance.now()) - start);
+}
+function countCategoryAudits(refs, plugins) {
+  const groupLookup = plugins.reduce(
+    (lookup, plugin) => {
+      if (plugin.groups == null || plugin.groups.length === 0) {
+        return lookup;
+      }
+      return {
+        ...lookup,
+        [plugin.slug]: Object.fromEntries(
+          plugin.groups.map((group) => [group.slug, group])
+        )
+      };
+    },
+    {}
+  );
+  return refs.reduce((acc, ref) => {
+    if (ref.type === "group") {
+      const groupRefs = groupLookup[ref.plugin]?.[ref.slug]?.refs;
+      return acc + (groupRefs?.length ?? 0);
+    }
+    return acc + 1;
+  }, 0);
+}
+function compareCategoryAuditsAndGroups(a, b) {
+  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;
+  }
+  return a.title.localeCompare(b.title);
+}
+function compareAudits(a, b) {
+  if (a.score !== b.score) {
+    return a.score - b.score;
+  }
+  if (a.value !== b.value) {
+    return b.value - a.value;
+  }
+  return a.title.localeCompare(b.title);
+}
+function compareIssueSeverity(severity1, severity2) {
+  const levels = {
+    info: 0,
+    warning: 1,
+    error: 2
+  };
+  return levels[severity1] - levels[severity2];
+}
+function throwIsNotPresentError(itemName, presentPlace) {
+  throw new Error(`${itemName} is not present in ${presentPlace}`);
+}
+function getPluginNameFromSlug(slug, plugins) {
+  return plugins.find(({ slug: pluginSlug }) => pluginSlug === slug)?.title || slug;
+}
+function compareIssues(a, b) {
+  if (a.severity !== b.severity) {
+    return -compareIssueSeverity(a.severity, b.severity);
+  }
+  if (!a.source && b.source) {
+    return -1;
+  }
+  if (a.source && !b.source) {
+    return 1;
+  }
+  if (a.source?.file !== b.source?.file) {
+    return a.source?.file.localeCompare(b.source?.file || "") ?? 0;
+  }
+  if (!a.source?.position && b.source?.position) {
+    return -1;
+  }
+  if (a.source?.position && !b.source?.position) {
+    return 1;
+  }
+  if (a.source?.position?.startLine !== b.source?.position?.startLine) {
+    return (a.source?.position?.startLine ?? 0) - (b.source?.position?.startLine ?? 0);
+  }
+  return 0;
+}
+function applyScoreColor({ score, text }, style = ansis) {
+  const formattedScore = text ?? formatReportScore(score);
+  if (score >= SCORE_COLOR_RANGE.GREEN_MIN) {
+    return text ? style.green(formattedScore) : style.bold(style.green(formattedScore));
+  }
+  if (score >= SCORE_COLOR_RANGE.YELLOW_MIN) {
+    return text ? style.yellow(formattedScore) : style.bold(style.yellow(formattedScore));
+  }
+  return text ? style.red(formattedScore) : style.bold(style.red(formattedScore));
+}
+function targetScoreIcon(score, targetScore, options2 = {}) {
+  if (targetScore != null) {
+    const {
+      passIcon = "\u2705",
+      failIcon = "\u274C",
+      prefix = "",
+      postfix = ""
+    } = options2;
+    if (score >= targetScore) {
+      return `${prefix}${passIcon}${postfix}`;
+    }
+    return `${prefix}${failIcon}${postfix}`;
+  }
+  return "";
+}
+
+// packages/utils/src/lib/execute-process.ts
+var ProcessError = class extends Error {
+  code;
+  stderr;
+  stdout;
+  constructor(result) {
+    super(result.stderr);
+    this.code = result.code;
+    this.stderr = result.stderr;
+    this.stdout = result.stdout;
+  }
+};
+function executeProcess(cfg) {
+  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 spawnedProcess = spawn(command2, args ?? [], {
+      shell: true,
+      ...options2
+    });
+    let stdout = "";
+    let stderr = "";
+    spawnedProcess.stdout.on("data", (data) => {
+      stdout += String(data);
+      onStdout?.(String(data), spawnedProcess);
+    });
+    spawnedProcess.stderr.on("data", (data) => {
+      stderr += String(data);
+      onStderr?.(String(data), spawnedProcess);
+    });
+    spawnedProcess.on("error", (err) => {
+      stderr += err.toString();
+    });
+    spawnedProcess.on("close", (code2) => {
+      const timings = { date, duration: calcDuration(start) };
+      if (code2 === 0 || ignoreExitCode) {
+        onComplete?.();
+        resolve({ code: code2, stdout, stderr, ...timings });
+      } else {
+        const errorMsg = new ProcessError({ code: code2, stdout, stderr, ...timings });
+        onError?.(errorMsg);
+        reject(errorMsg);
+      }
+    });
+  });
+}
 
 // packages/utils/src/lib/file-system.ts
+import { bold, gray } from "ansis";
 import { bundleRequire } from "bundle-require";
-import chalk2 from "chalk";
 import { mkdir, readFile, readdir, rm, stat } from "node:fs/promises";
 
 // packages/utils/src/lib/formatting.ts
@@ -823,55 +1096,7 @@ function isPromiseRejectedResult(result) {
 // 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 SCORE_COLOR_RANGE = {
-  GREEN_MIN: 0.9,
-  YELLOW_MIN: 0.5
-};
-var CATEGORIES_TITLE = "\u{1F3F7} Categories";
-var FOOTER_PREFIX = "Made with \u2764 by";
-var CODE_PUSHUP_DOMAIN = "code-pushup.dev";
-var README_LINK = "https://github.com/code-pushup/cli#readme";
-var reportHeadlineText = "Code PushUp Report";
-var reportOverviewTableHeaders = [
-  {
-    key: "category",
-    label: "\u{1F3F7} Category",
-    align: "left"
-  },
-  {
-    key: "score",
-    label: "\u2B50 Score"
-  },
-  {
-    key: "audits",
-    label: "\u{1F6E1} Audits"
-  }
-];
-var reportRawOverviewTableHeaders = ["Category", "Score", "Audits"];
-var issuesTableHeadings = [
-  {
-    key: "severity",
-    label: "Severity"
-  },
-  {
-    key: "message",
-    label: "Message"
-  },
-  {
-    key: "file",
-    label: "Source file"
-  },
-  {
-    key: "line",
-    label: "Line(s)"
-  }
-];
-
-// packages/utils/src/lib/logging.ts
+import { underline } from "ansis";
 var singletonUiInstance;
 function ui() {
   if (singletonUiInstance === void 0) {
@@ -895,7 +1120,7 @@ function logListItem(args) {
   singletonUiInstance?.logger.log(content);
 }
 function link(text) {
-  return chalk.underline(chalk.blueBright(text));
+  return underline.blueBright(text);
 }
 
 // packages/utils/src/lib/log-results.ts
@@ -970,10 +1195,10 @@ async function ensureDirectoryExists(baseDir) {
 function logMultipleFileResults(fileResults, messagePrefix) {
   const succeededTransform = (result) => {
     const [fileName, size] = result.value;
-    const formattedSize = size ? ` (${chalk2.gray(formatBytes(size))})` : "";
-    return `- ${chalk2.bold(fileName)}${formattedSize}`;
+    const formattedSize = size ? ` (${gray(formatBytes(size))})` : "";
+    return `- ${bold(fileName)}${formattedSize}`;
   };
-  const failedTransform = (result) => `- ${chalk2.bold(result.reason)}`;
+  const failedTransform = (result) => `- ${bold(result.reason)}`;
   logMultipleResults(
     fileResults,
     messagePrefix,
@@ -989,38 +1214,17 @@ async function importModule(options2) {
   return mod;
 }
 
-// packages/utils/src/lib/text-formats/constants.ts
-var NEW_LINE = "\n";
-var TAB = "  ";
-var SPACE = " ";
-
-// packages/utils/src/lib/text-formats/html/details.ts
-function details(title, content, cfg = { open: false }) {
-  return `<details${cfg.open ? " open" : ""}>${NEW_LINE}<summary>${title}</summary>${NEW_LINE}${// ⚠️ The blank line is needed to ensure Markdown in content is rendered correctly.
-  NEW_LINE}${content}${NEW_LINE}${// @TODO in the future we could consider adding it only if the content ends with a code block
-  // ⚠️ The blank line ensure Markdown in content is rendered correctly.
-  NEW_LINE}</details>${// ⚠️ The blank line is needed to ensure Markdown after details is rendered correctly.
-  NEW_LINE}`;
-}
-
-// packages/utils/src/lib/text-formats/html/font-style.ts
-var boldElement = "b";
-function bold(text) {
-  return `<${boldElement}>${text}</${boldElement}>`;
-}
-var italicElement = "i";
-function italic(text) {
-  return `<${italicElement}>${text}</${italicElement}>`;
-}
-var codeElement = "code";
-function code(text) {
-  return `<${codeElement}>${text}</${codeElement}>`;
+// 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/text-formats/html/link.ts
-function link2(href, text) {
-  return `<a href="${href}">${text || href}</a>`;
-}
+// packages/utils/src/lib/git/git.ts
+import { isAbsolute, join, relative } from "node:path";
+import { simpleGit } from "simple-git";
 
 // packages/utils/src/lib/transform.ts
 function toArray(val) {
@@ -1041,6 +1245,262 @@ function capitalize(text) {
   )}`;
 }
 
+// packages/utils/src/lib/git/git.ts
+function getGitRoot(git = simpleGit()) {
+  return git.revparse("--show-toplevel");
+}
+function formatGitPath(path, gitRoot) {
+  const absolutePath = isAbsolute(path) ? path : join(process.cwd(), path);
+  const relativePath = relative(gitRoot, absolutePath);
+  return toUnixPath(relativePath);
+}
+var GitStatusError = class _GitStatusError extends Error {
+  static ignoredProps = /* @__PURE__ */ new Set(["current", "tracking"]);
+  static getReducedStatus(status) {
+    return Object.fromEntries(
+      Object.entries(status).filter(([key]) => !this.ignoredProps.has(key)).filter(
+        (entry) => {
+          const value = entry[1];
+          if (value == null) {
+            return false;
+          }
+          if (Array.isArray(value) && value.length === 0) {
+            return false;
+          }
+          if (typeof value === "number" && value === 0) {
+            return false;
+          }
+          return !(typeof value === "boolean" && !value);
+        }
+      )
+    );
+  }
+  constructor(status) {
+    super(
+      `Working directory needs to be clean before we you can proceed. Commit your local changes or stash them: 
+ ${JSON.stringify(
+        _GitStatusError.getReducedStatus(status),
+        null,
+        2
+      )}`
+    );
+  }
+};
+async function guardAgainstLocalChanges(git = simpleGit()) {
+  const status = await git.status(["-s"]);
+  if (status.files.length > 0) {
+    throw new GitStatusError(status);
+  }
+}
+async function safeCheckout(branchOrHash, forceCleanStatus = false, git = simpleGit()) {
+  if (forceCleanStatus) {
+    await git.raw(["reset", "--hard"]);
+    await git.clean(["f", "d"]);
+    ui().logger.info(`git status cleaned`);
+  }
+  await guardAgainstLocalChanges(git);
+  await git.checkout(branchOrHash);
+}
+
+// packages/utils/src/lib/git/git.commits-and-tags.ts
+import { simpleGit as simpleGit2 } from "simple-git";
+
+// packages/utils/src/lib/semver.ts
+import { rcompare, valid } from "semver";
+function normalizeSemver(semverString) {
+  if (semverString.startsWith("v") || semverString.startsWith("V")) {
+    return semverString.slice(1);
+  }
+  if (semverString.includes("@")) {
+    return semverString.split("@").at(-1) ?? "";
+  }
+  return semverString;
+}
+function isSemver(semverString = "") {
+  return valid(normalizeSemver(semverString)) != null;
+}
+
+// packages/utils/src/lib/git/git.commits-and-tags.ts
+async function getLatestCommit(git = simpleGit2()) {
+  const log2 = await git.log({
+    maxCount: 1,
+    // git log -1 --pretty=format:"%H %s %an %aI" - See: https://git-scm.com/docs/pretty-formats
+    format: { hash: "%H", message: "%s", author: "%an", date: "%aI" }
+  });
+  return commitSchema.parse(log2.latest);
+}
+async function getCurrentBranchOrTag(git = simpleGit2()) {
+  return await git.branch().then((r) => r.current) || // If no current branch, try to get the tag
+  // @TODO use simple git
+  await git.raw(["describe", "--tags", "--exact-match"]).then((out) => out.trim());
+}
+function validateFilter({ from, to }) {
+  if (to && !from) {
+    throw new Error(
+      `filter needs the "from" option defined to accept the "to" option.
+`
+    );
+  }
+}
+function filterLogs(allTags, opt) {
+  if (!opt) {
+    return allTags;
+  }
+  validateFilter(opt);
+  const { from, to, maxCount } = opt;
+  const finIndex = (tagName, fallback) => {
+    const idx = allTags.indexOf(tagName ?? "");
+    if (idx > -1) {
+      return idx;
+    }
+    return fallback;
+  };
+  const fromIndex = finIndex(from, 0);
+  const toIndex = finIndex(to, void 0);
+  return allTags.slice(fromIndex, toIndex ? toIndex + 1 : toIndex).slice(0, maxCount ?? void 0);
+}
+async function getHashFromTag(tag, git = simpleGit2()) {
+  const tagDetails = await git.show(["--no-patch", "--format=%H", tag]);
+  const hash = tagDetails.trim();
+  return {
+    hash: hash.split("\n").at(-1) ?? "",
+    message: tag
+  };
+}
+async function getSemverTags(opt = {}, git = simpleGit2()) {
+  validateFilter(opt);
+  const { targetBranch, ...options2 } = opt;
+  let currentBranch;
+  if (targetBranch) {
+    currentBranch = await getCurrentBranchOrTag(git);
+    await git.checkout(targetBranch);
+  }
+  const tagsRaw = await git.tag([
+    "--merged",
+    targetBranch ?? await getCurrentBranchOrTag(git)
+  ]);
+  const allTags = tagsRaw.split(/\n/).map((tag) => tag.trim()).filter(Boolean).filter(isSemver);
+  const relevantTags = filterLogs(allTags, options2);
+  const tagsWithHashes = await Promise.all(
+    relevantTags.map((tag) => getHashFromTag(tag, git))
+  );
+  if (currentBranch) {
+    await git.checkout(currentBranch);
+  }
+  return tagsWithHashes;
+}
+async function getHashes(options2 = {}, git = simpleGit2()) {
+  const { targetBranch, from, to, maxCount, ...opt } = options2;
+  validateFilter({ from, to });
+  let currentBranch;
+  if (targetBranch) {
+    currentBranch = await getCurrentBranchOrTag(git);
+    await git.checkout(targetBranch);
+  }
+  const logs = await git.log({
+    ...opt,
+    format: {
+      hash: "%H",
+      message: "%s"
+    },
+    from,
+    to,
+    maxCount
+  });
+  if (targetBranch) {
+    await git.checkout(currentBranch);
+  }
+  return [...logs.all];
+}
+
+// packages/utils/src/lib/group-by-status.ts
+function groupByStatus(results) {
+  return results.reduce(
+    (acc, result) => result.status === "fulfilled" ? { ...acc, fulfilled: [...acc.fulfilled, result] } : { ...acc, rejected: [...acc.rejected, result] },
+    { fulfilled: [], rejected: [] }
+  );
+}
+
+// packages/utils/src/lib/progress.ts
+import { black, bold as bold2, gray as gray2, green } from "ansis";
+import { MultiProgressBars } from "multi-progress-bars";
+var barStyles = {
+  active: (s) => green(s),
+  done: (s) => gray2(s),
+  idle: (s) => gray2(s)
+};
+var messageStyles = {
+  active: (s) => black(s),
+  done: (s) => bold2.green(s),
+  idle: (s) => gray2(s)
+};
+var mpb;
+function getSingletonProgressBars(options2) {
+  if (!mpb) {
+    mpb = new MultiProgressBars({
+      progressWidth: TERMINAL_WIDTH,
+      initMessage: "",
+      border: true,
+      ...options2
+    });
+  }
+  return mpb;
+}
+function getProgressBar(taskName) {
+  const tasks = getSingletonProgressBars();
+  tasks.addTask(taskName, {
+    type: "percentage",
+    percentage: 0,
+    message: "",
+    barTransformFn: barStyles.idle
+  });
+  return {
+    incrementInSteps: (numPlugins) => {
+      tasks.incrementTask(taskName, {
+        percentage: 1 / numPlugins,
+        barTransformFn: barStyles.active
+      });
+    },
+    updateTitle: (title) => {
+      tasks.updateTask(taskName, {
+        message: title,
+        barTransformFn: barStyles.active
+      });
+    },
+    endProgress: (message = "") => {
+      tasks.done(taskName, {
+        message: messageStyles.done(message),
+        barTransformFn: barStyles.done
+      });
+    }
+  };
+}
+
+// packages/utils/src/lib/reports/flatten-plugins.ts
+function listGroupsFromAllPlugins(report) {
+  return report.plugins.flatMap(
+    (plugin) => plugin.groups?.map((group) => ({ plugin, group })) ?? []
+  );
+}
+function listAuditsFromAllPlugins(report) {
+  return report.plugins.flatMap(
+    (plugin) => plugin.audits.map((audit) => ({ plugin, audit }))
+  );
+}
+
+// packages/utils/src/lib/reports/generate-md-report.ts
+import { MarkdownDocument as MarkdownDocument3, md as md4 } from "build-md";
+
+// packages/utils/src/lib/text-formats/constants.ts
+var HIERARCHY = {
+  level_1: 1,
+  level_2: 2,
+  level_3: 3,
+  level_4: 4,
+  level_5: 5,
+  level_6: 6
+};
+
 // packages/utils/src/lib/text-formats/table.ts
 function rowToStringArray({ rows, columns = [] }) {
   if (Array.isArray(rows.at(0)) && typeof columns.at(0) === "object") {
@@ -1130,254 +1590,53 @@ function getColumnAlignments(tableData) {
   return Object.keys(biggestRow ?? {}).map((_) => "center");
 }
 
-// packages/utils/src/lib/text-formats/html/table.ts
-function wrap(elem, content) {
-  return `<${elem}>${content}</${elem}>${NEW_LINE}`;
-}
-function wrapRow(content) {
-  const elem = "tr";
-  return `<${elem}>${NEW_LINE}${content}</${elem}>${NEW_LINE}`;
-}
-function table(tableData) {
+// packages/utils/src/lib/reports/formatting.ts
+import {
+  MarkdownDocument,
+  md as md2
+} from "build-md";
+function tableSection(tableData, options2) {
   if (tableData.rows.length === 0) {
-    throw new Error("Data can't be empty");
-  }
-  const tableHeaderCols = columnsToStringArray(tableData).map((s) => wrap("th", s)).join("");
-  const tableHeaderRow = wrapRow(tableHeaderCols);
-  const tableBody = rowToStringArray(tableData).map((arr) => {
-    const columns = arr.map((s) => wrap("td", s)).join("");
-    return wrapRow(columns);
-  }).join("");
-  return wrap("table", `${NEW_LINE}${tableHeaderRow}${tableBody}`);
-}
-
-// packages/utils/src/lib/text-formats/md/font-style.ts
-var boldWrap = "**";
-function bold2(text) {
-  return `${boldWrap}${text}${boldWrap}`;
-}
-var italicWrap = "_";
-function italic2(text) {
-  return `${italicWrap}${text}${italicWrap}`;
-}
-var strikeThroughWrap = "~";
-function strikeThrough(text) {
-  return `${strikeThroughWrap}${text}${strikeThroughWrap}`;
-}
-var codeWrap = "`";
-function code2(text) {
-  return `${codeWrap}${text}${codeWrap}`;
-}
-
-// packages/utils/src/lib/text-formats/md/headline.ts
-function headline(text, hierarchy = 1) {
-  return `${"#".repeat(hierarchy)} ${text}${NEW_LINE}`;
-}
-function h(text, hierarchy = 1) {
-  return headline(text, hierarchy);
-}
-function h1(text) {
-  return headline(text, 1);
-}
-function h2(text) {
-  return headline(text, 2);
-}
-function h3(text) {
-  return headline(text, 3);
-}
-function h4(text) {
-  return headline(text, 4);
-}
-function h5(text) {
-  return headline(text, 5);
-}
-function h6(text) {
-  return headline(text, 6);
-}
-
-// packages/utils/src/lib/text-formats/md/image.ts
-function image(src, alt) {
-  return `![${alt}](${src})`;
-}
-
-// packages/utils/src/lib/text-formats/md/link.ts
-function link3(href, text) {
-  return `[${text || href}](${href})`;
-}
-
-// packages/utils/src/lib/text-formats/md/list.ts
-function li(text, order = "unordered") {
-  const style = order === "unordered" ? "-" : "- [ ]";
-  return `${style} ${text}`;
-}
-function indentation(text, level = 1) {
-  return `${TAB.repeat(level)}${text}`;
-}
-
-// packages/utils/src/lib/text-formats/md/paragraphs.ts
-function paragraphs(...sections) {
-  return sections.filter(Boolean).join(`${NEW_LINE}${NEW_LINE}`);
-}
-
-// packages/utils/src/lib/text-formats/md/section.ts
-function section(...contents) {
-  return `${lines(...contents)}${NEW_LINE}`;
-}
-function lines(...contents) {
-  const filteredContent = contents.filter(
-    (value) => value != null && value !== "" && value !== false
-  );
-  return `${filteredContent.join(NEW_LINE)}`;
-}
-
-// packages/utils/src/lib/text-formats/md/table.ts
-var alignString = /* @__PURE__ */ new Map([
-  ["left", ":--"],
-  ["center", ":--:"],
-  ["right", "--:"]
-]);
-function tableRow(rows) {
-  return `|${rows.join("|")}|`;
-}
-function table2(data) {
-  if (data.rows.length === 0) {
-    throw new Error("Data can't be empty");
-  }
-  const alignmentRow = getColumnAlignments(data).map(
-    (s) => alignString.get(s) ?? String(alignString.get("center"))
-  );
-  return section(
-    `${lines(
-      tableRow(columnsToStringArray(data)),
-      tableRow(alignmentRow),
-      ...rowToStringArray(data).map(tableRow)
-    )}`
+    return null;
+  }
+  const { level = HIERARCHY.level_4 } = options2 ?? {};
+  const columns = columnsToStringArray(tableData);
+  const alignments = getColumnAlignments(tableData);
+  const rows = rowToStringArray(tableData);
+  return new MarkdownDocument().heading(level, tableData.title).table(
+    columns.map((heading, i) => {
+      const alignment = alignments[i];
+      if (alignment) {
+        return { heading, alignment };
+      }
+      return heading;
+    }),
+    rows
   );
 }
+function metaDescription(audit) {
+  const docsUrl = audit.docsUrl;
+  const description = audit.description?.trim();
+  if (docsUrl) {
+    const docsLink = md2.link(docsUrl, "\u{1F4D6} Docs");
+    if (!description) {
+      return docsLink;
+    }
+    const parsedDescription = description.endsWith("```") ? `${description}
 
-// packages/utils/src/lib/text-formats/index.ts
-var md = {
-  bold: bold2,
-  italic: italic2,
-  strikeThrough,
-  code: code2,
-  link: link3,
-  image,
-  headline,
-  h,
-  h1,
-  h2,
-  h3,
-  h4,
-  h5,
-  h6,
-  indentation,
-  lines,
-  li,
-  section,
-  paragraphs,
-  table: table2
-};
-var html = {
-  bold,
-  italic,
-  code,
-  link: link2,
-  details,
-  table
-};
-
-// packages/utils/src/lib/reports/utils.ts
-var { image: image2, bold: boldMd } = md;
-function formatReportScore(score) {
-  const scaledScore = score * 100;
-  const roundedScore = Math.round(scaledScore);
-  return roundedScore === 100 && score !== 1 ? Math.floor(scaledScore).toString() : roundedScore.toString();
-}
-function formatScoreWithColor(score, options2) {
-  const styledNumber = options2?.skipBold ? formatReportScore(score) : boldMd(formatReportScore(score));
-  return `${scoreMarker(score)} ${styledNumber}`;
-}
-var MARKERS = {
-  circle: {
-    red: "\u{1F534}",
-    yellow: "\u{1F7E1}",
-    green: "\u{1F7E2}"
-  },
-  square: {
-    red: "\u{1F7E5}",
-    yellow: "\u{1F7E8}",
-    green: "\u{1F7E9}"
-  }
-};
-function scoreMarker(score, markerType = "circle") {
-  if (score >= SCORE_COLOR_RANGE.GREEN_MIN) {
-    return MARKERS[markerType].green;
-  }
-  if (score >= SCORE_COLOR_RANGE.YELLOW_MIN) {
-    return MARKERS[markerType].yellow;
-  }
-  return MARKERS[markerType].red;
-}
-function getDiffMarker(diff) {
-  if (diff > 0) {
-    return "\u2191";
+` : `${description} `;
+    return md2`${parsedDescription}${docsLink}`;
   }
-  if (diff < 0) {
-    return "\u2193";
+  if (description && description.trim().length > 0) {
+    return description;
   }
   return "";
 }
-function colorByScoreDiff(text, diff) {
-  const color = diff > 0 ? "green" : diff < 0 ? "red" : "gray";
-  return shieldsBadge(text, color);
-}
-function shieldsBadge(text, color) {
-  return image2(
-    `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 severityMarker(severity) {
-  if (severity === "error") {
-    return "\u{1F6A8}";
-  }
-  if (severity === "warning") {
-    return "\u26A0\uFE0F";
-  }
-  return "\u2139\uFE0F";
-}
-function calcDuration(start, stop) {
-  return Math.round((stop ?? performance.now()) - start);
-}
-function countCategoryAudits(refs, plugins) {
-  const groupLookup = plugins.reduce(
-    (lookup, plugin) => {
-      if (plugin.groups == null || plugin.groups.length === 0) {
-        return lookup;
-      }
-      return {
-        ...lookup,
-        [plugin.slug]: Object.fromEntries(
-          plugin.groups.map((group) => [group.slug, group])
-        )
-      };
-    },
-    {}
-  );
-  return refs.reduce((acc, ref) => {
-    if (ref.type === "group") {
-      const groupRefs = groupLookup[ref.plugin]?.[ref.slug]?.refs;
-      return acc + (groupRefs?.length ?? 0);
-    }
-    return acc + 1;
-  }, 0);
-}
+
+// packages/utils/src/lib/reports/generate-md-report-categoy-section.ts
+import { MarkdownDocument as MarkdownDocument2, md as md3 } from "build-md";
+
+// packages/utils/src/lib/reports/sorting.ts
 function getSortableAuditByRef({ slug, weight, plugin }, plugins) {
   const auditPlugin = plugins.find((p) => p.slug === plugin);
   if (!auditPlugin) {
@@ -1395,6 +1654,19 @@ function getSortableAuditByRef({ slug, weight, plugin }, plugins) {
     plugin
   };
 }
+function getSortedGroupAudits(group, plugin, plugins) {
+  return group.refs.map(
+    (ref) => getSortableAuditByRef(
+      {
+        plugin,
+        slug: ref.slug,
+        weight: ref.weight,
+        type: "audit"
+      },
+      plugins
+    )
+  ).sort(compareCategoryAuditsAndGroups);
+}
 function getSortableGroupByRef({ plugin, slug, weight }, plugins) {
   const groupPlugin = plugins.find((p) => p.slug === plugin);
   if (!groupPlugin) {
@@ -1419,849 +1691,280 @@ function getSortableGroupByRef({ plugin, slug, weight }, plugins) {
     weight
   };
 }
-function getSortedGroupAudits(group, plugin, plugins) {
-  return group.refs.map(
-    (ref) => getSortableAuditByRef(
-      {
-        plugin,
-        slug: ref.slug,
-        weight: ref.weight,
-        type: "audit"
-      },
-      plugins
-    )
-  ).sort(compareCategoryAuditsAndGroups);
-}
-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 ("value" in a && "value" in b && a.value !== b.value) {
-    return b.value - a.value;
-  }
-  return a.title.localeCompare(b.title);
-}
-function compareAudits(a, b) {
-  if (a.score !== b.score) {
-    return a.score - b.score;
-  }
-  if (a.value !== b.value) {
-    return b.value - a.value;
-  }
-  return a.title.localeCompare(b.title);
-}
-function compareIssueSeverity(severity1, severity2) {
-  const levels = {
-    info: 0,
-    warning: 1,
-    error: 2
+function sortReport(report) {
+  const { categories, plugins } = report;
+  const sortedCategories = categories.map((category) => {
+    const { audits, groups: groups2 } = category.refs.reduce(
+      (acc, ref) => ({
+        ...acc,
+        ...ref.type === "group" ? {
+          groups: [...acc.groups, getSortableGroupByRef(ref, plugins)]
+        } : {
+          audits: [...acc.audits, getSortableAuditByRef(ref, plugins)]
+        }
+      }),
+      { groups: [], audits: [] }
+    );
+    const sortedAuditsAndGroups = [...audits, ...groups2].sort(
+      compareCategoryAuditsAndGroups
+    );
+    const sortedRefs = [...category.refs].sort((a, b) => {
+      const aIndex = sortedAuditsAndGroups.findIndex(
+        (ref) => ref.slug === a.slug && ref.plugin === a.plugin
+      );
+      const bIndex = sortedAuditsAndGroups.findIndex(
+        (ref) => ref.slug === b.slug && ref.plugin === b.plugin
+      );
+      return aIndex - bIndex;
+    });
+    return { ...category, refs: sortedRefs };
+  });
+  return {
+    ...report,
+    categories: sortedCategories,
+    plugins: sortPlugins(plugins)
   };
-  return levels[severity1] - levels[severity2];
 }
-async function loadReport(options2) {
-  const { outputDir, filename, format } = options2;
-  await ensureDirectoryExists(outputDir);
-  const filePath = join(outputDir, `${filename}.${format}`);
-  if (format === "json") {
-    const content = await readJsonFile(filePath);
-    return reportSchema.parse(content);
-  }
-  const text = await readTextFile(filePath);
-  return text;
+function sortPlugins(plugins) {
+  return plugins.map((plugin) => ({
+    ...plugin,
+    audits: [...plugin.audits].sort(compareAudits).map(
+      (audit) => audit.details?.issues ? {
+        ...audit,
+        details: {
+          ...audit.details,
+          issues: [...audit.details.issues].sort(compareIssues)
+        }
+      } : audit
+    )
+  }));
 }
-function throwIsNotPresentError(itemName, presentPlace) {
-  throw new Error(`${itemName} is not present in ${presentPlace}`);
+
+// packages/utils/src/lib/reports/generate-md-report-categoy-section.ts
+function categoriesOverviewSection(report) {
+  const { categories, plugins } = report;
+  return new MarkdownDocument2().table(
+    [
+      { heading: "\u{1F3F7} Category", alignment: "left" },
+      { heading: "\u2B50 Score", alignment: "center" },
+      { heading: "\u{1F6E1} Audits", alignment: "center" }
+    ],
+    categories.map(({ title, refs, score, isBinary }) => [
+      // @TODO refactor `isBinary: boolean` to `targetScore: number` #713
+      // The heading "ID" is inferred from the heading text in Markdown.
+      md3.link(`#${slugify(title)}`, title),
+      md3`${scoreMarker(score)} ${md3.bold(
+        formatReportScore(score)
+      )}${binaryIconSuffix(score, isBinary)}`,
+      countCategoryAudits(refs, plugins).toString()
+    ])
+  );
 }
-function getPluginNameFromSlug(slug, plugins) {
-  return plugins.find(({ slug: pluginSlug }) => pluginSlug === slug)?.title || slug;
-}
-function compareIssues(a, b) {
-  if (a.severity !== b.severity) {
-    return -compareIssueSeverity(a.severity, b.severity);
-  }
-  if (!a.source && b.source) {
-    return -1;
-  }
-  if (a.source && !b.source) {
-    return 1;
-  }
-  if (a.source?.file !== b.source?.file) {
-    return a.source?.file.localeCompare(b.source?.file || "") ?? 0;
-  }
-  if (!a.source?.position && b.source?.position) {
-    return -1;
-  }
-  if (a.source?.position && !b.source?.position) {
-    return 1;
-  }
-  if (a.source?.position?.startLine !== b.source?.position?.startLine) {
-    return (a.source?.position?.startLine ?? 0) - (b.source?.position?.startLine ?? 0);
-  }
-  return 0;
-}
-
-// packages/utils/src/lib/execute-process.ts
-var ProcessError = class extends Error {
-  code;
-  stderr;
-  stdout;
-  constructor(result) {
-    super(result.stderr);
-    this.code = result.code;
-    this.stderr = result.stderr;
-    this.stdout = result.stdout;
-  }
-};
-function executeProcess(cfg) {
-  const { observer, cwd, command: command2, args, ignoreExitCode = false } = cfg;
-  const { onStdout, 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 });
-    let stdout = "";
-    let stderr = "";
-    process2.stdout.on("data", (data) => {
-      stdout += String(data);
-      onStdout?.(String(data));
-    });
-    process2.stderr.on("data", (data) => {
-      stderr += String(data);
-    });
-    process2.on("error", (err) => {
-      stderr += err.toString();
-    });
-    process2.on("close", (code3) => {
-      const timings = { date, duration: calcDuration(start) };
-      if (code3 === 0 || ignoreExitCode) {
-        onComplete?.();
-        resolve({ code: code3, stdout, stderr, ...timings });
-      } else {
-        const errorMsg = new ProcessError({ code: code3, stdout, stderr, ...timings });
-        onError?.(errorMsg);
-        reject(errorMsg);
-      }
-    });
-  });
-}
-
-// 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/git.ts
-import { isAbsolute, join as join2, relative } from "node:path";
-import { simpleGit } from "simple-git";
-function getGitRoot(git = simpleGit()) {
-  return git.revparse("--show-toplevel");
-}
-function formatGitPath(path, gitRoot) {
-  const absolutePath = isAbsolute(path) ? path : join2(process.cwd(), path);
-  const relativePath = relative(gitRoot, absolutePath);
-  return toUnixPath(relativePath);
-}
-var GitStatusError = class _GitStatusError extends Error {
-  static ignoredProps = /* @__PURE__ */ new Set(["current", "tracking"]);
-  static getReducedStatus(status) {
-    return Object.fromEntries(
-      Object.entries(status).filter(([key]) => !this.ignoredProps.has(key)).filter(
-        (entry) => {
-          const value = entry[1];
-          if (value == null) {
-            return false;
-          }
-          if (Array.isArray(value) && value.length === 0) {
-            return false;
-          }
-          if (typeof value === "number" && value === 0) {
-            return false;
-          }
-          return !(typeof value === "boolean" && !value);
-        }
-      )
-    );
-  }
-  constructor(status) {
-    super(
-      `Working directory needs to be clean before we you can proceed. Commit your local changes or stash them: 
- ${JSON.stringify(
-        _GitStatusError.getReducedStatus(status),
-        null,
-        2
-      )}`
-    );
-  }
-};
-async function guardAgainstLocalChanges(git = simpleGit()) {
-  const status = await git.status(["-s"]);
-  if (status.files.length > 0) {
-    throw new GitStatusError(status);
-  }
-}
-async function safeCheckout(branchOrHash, forceCleanStatus = false, git = simpleGit()) {
-  if (forceCleanStatus) {
-    await git.raw(["reset", "--hard"]);
-    await git.clean(["f", "d"]);
-    ui().logger.info(`git status cleaned`);
-  }
-  await guardAgainstLocalChanges(git);
-  await git.checkout(branchOrHash);
-}
-
-// packages/utils/src/lib/git/git.commits-and-tags.ts
-import { simpleGit as simpleGit2 } from "simple-git";
-
-// packages/utils/src/lib/semver.ts
-import { rcompare, valid } from "semver";
-function normalizeSemver(semverString) {
-  if (semverString.startsWith("v") || semverString.startsWith("V")) {
-    return semverString.slice(1);
-  }
-  if (semverString.includes("@")) {
-    return semverString.split("@").at(-1) ?? "";
-  }
-  return semverString;
-}
-function isSemver(semverString = "") {
-  return valid(normalizeSemver(semverString)) != null;
-}
-
-// packages/utils/src/lib/git/git.commits-and-tags.ts
-async function getLatestCommit(git = simpleGit2()) {
-  const log2 = await git.log({
-    maxCount: 1,
-    // git log -1 --pretty=format:"%H %s %an %aI" - See: https://git-scm.com/docs/pretty-formats
-    format: { hash: "%H", message: "%s", author: "%an", date: "%aI" }
-  });
-  return commitSchema.parse(log2.latest);
-}
-async function getCurrentBranchOrTag(git = simpleGit2()) {
-  return await git.branch().then((r) => r.current) || // If no current branch, try to get the tag
-  // @TODO use simple git
-  await git.raw(["describe", "--tags", "--exact-match"]).then((out) => out.trim());
-}
-function validateFilter({ from, to }) {
-  if (to && !from) {
-    throw new Error(
-      `filter needs the "from" option defined to accept the "to" option.
-`
-    );
-  }
-}
-function filterLogs(allTags, opt) {
-  if (!opt) {
-    return allTags;
-  }
-  validateFilter(opt);
-  const { from, to, maxCount } = opt;
-  const finIndex = (tagName, fallback) => {
-    const idx = allTags.indexOf(tagName ?? "");
-    if (idx > -1) {
-      return idx;
-    }
-    return fallback;
-  };
-  const fromIndex = finIndex(from, 0);
-  const toIndex = finIndex(to, void 0);
-  return allTags.slice(fromIndex, toIndex ? toIndex + 1 : toIndex).slice(0, maxCount ?? void 0);
-}
-async function getHashFromTag(tag, git = simpleGit2()) {
-  const tagDetails = await git.show(["--no-patch", "--format=%H", tag]);
-  const hash = tagDetails.trim();
-  return {
-    hash: hash.split("\n").at(-1) ?? "",
-    message: tag
-  };
-}
-async function getSemverTags(opt = {}, git = simpleGit2()) {
-  validateFilter(opt);
-  const { targetBranch, ...options2 } = opt;
-  let currentBranch;
-  if (targetBranch) {
-    currentBranch = await getCurrentBranchOrTag(git);
-    await git.checkout(targetBranch);
-  }
-  const tagsRaw = await git.tag([
-    "--merged",
-    targetBranch ?? await getCurrentBranchOrTag(git)
-  ]);
-  const allTags = tagsRaw.split(/\n/).map((tag) => tag.trim()).filter(Boolean).filter(isSemver);
-  const relevantTags = filterLogs(allTags, options2);
-  const tagsWithHashes = await Promise.all(
-    relevantTags.map((tag) => getHashFromTag(tag, git))
-  );
-  if (currentBranch) {
-    await git.checkout(currentBranch);
-  }
-  return tagsWithHashes;
-}
-async function getHashes(options2 = {}, git = simpleGit2()) {
-  const { targetBranch, from, to, maxCount, ...opt } = options2;
-  validateFilter({ from, to });
-  let currentBranch;
-  if (targetBranch) {
-    currentBranch = await getCurrentBranchOrTag(git);
-    await git.checkout(targetBranch);
-  }
-  const logs = await git.log({
-    ...opt,
-    format: {
-      hash: "%H",
-      message: "%s"
-    },
-    from,
-    to,
-    maxCount
-  });
-  if (targetBranch) {
-    await git.checkout(currentBranch);
-  }
-  return [...logs.all];
-}
-
-// packages/utils/src/lib/group-by-status.ts
-function groupByStatus(results) {
-  return results.reduce(
-    (acc, result) => result.status === "fulfilled" ? { ...acc, fulfilled: [...acc.fulfilled, result] } : { ...acc, rejected: [...acc.rejected, result] },
-    { fulfilled: [], rejected: [] }
-  );
-}
-
-// packages/utils/src/lib/progress.ts
-import chalk3 from "chalk";
-import { MultiProgressBars } from "multi-progress-bars";
-var barStyles = {
-  active: (s) => chalk3.green(s),
-  done: (s) => chalk3.gray(s),
-  idle: (s) => chalk3.gray(s)
-};
-var messageStyles = {
-  active: (s) => chalk3.black(s),
-  done: (s) => chalk3.green(chalk3.bold(s)),
-  idle: (s) => chalk3.gray(s)
-};
-var mpb;
-function getSingletonProgressBars(options2) {
-  if (!mpb) {
-    mpb = new MultiProgressBars({
-      progressWidth: TERMINAL_WIDTH,
-      initMessage: "",
-      border: true,
-      ...options2
-    });
-  }
-  return mpb;
-}
-function getProgressBar(taskName) {
-  const tasks = getSingletonProgressBars();
-  tasks.addTask(taskName, {
-    type: "percentage",
-    percentage: 0,
-    message: "",
-    barTransformFn: barStyles.idle
-  });
-  return {
-    incrementInSteps: (numPlugins) => {
-      tasks.incrementTask(taskName, {
-        percentage: 1 / numPlugins,
-        barTransformFn: barStyles.active
-      });
-    },
-    updateTitle: (title) => {
-      tasks.updateTask(taskName, {
-        message: title,
-        barTransformFn: barStyles.active
-      });
-    },
-    endProgress: (message = "") => {
-      tasks.done(taskName, {
-        message: messageStyles.done(message),
-        barTransformFn: barStyles.done
-      });
-    }
-  };
-}
-
-// packages/utils/src/lib/reports/flatten-plugins.ts
-function listGroupsFromAllPlugins(report) {
-  return report.plugins.flatMap(
-    (plugin) => plugin.groups?.map((group) => ({ plugin, group })) ?? []
-  );
-}
-function listAuditsFromAllPlugins(report) {
-  return report.plugins.flatMap(
-    (plugin) => plugin.audits.map((audit) => ({ plugin, audit }))
-  );
-}
-
-// packages/utils/src/lib/reports/formatting.ts
-var { headline: headline2, lines: lines2, link: link4, section: section2, table: table3 } = md;
-function tableSection(tableData, options2) {
-  if (tableData.rows.length === 0) {
-    return "";
-  }
-  const { level = 4 } = options2 ?? {};
-  const render = (h7, l) => l === 0 ? h7 : headline2(h7, l);
-  return lines2(
-    tableData.title && render(tableData.title, level),
-    table3(tableData)
-  );
-}
-function metaDescription({
-  docsUrl,
-  description
-}) {
-  if (docsUrl) {
-    const docsLink = link4(docsUrl, "\u{1F4D6} Docs");
-    if (!description) {
-      return section2(docsLink);
-    }
-    const parsedDescription = description.toString().endsWith("```") ? `${description}${NEW_LINE + NEW_LINE}` : `${description}${SPACE}`;
-    return section2(`${parsedDescription}${docsLink}`);
-  }
-  if (description && description.trim().length > 0) {
-    return section2(description);
-  }
-  return "";
-}
-
-// packages/utils/src/lib/reports/generate-md-report-categoy-section.ts
-var { link: link5, section: section3, h2: h22, lines: lines3, li: li2, bold: boldMd2, h3: h32, indentation: indentation2 } = md;
-function categoriesOverviewSection(report) {
-  const { categories, plugins } = report;
-  if (categories.length > 0 && plugins.length > 0) {
-    const tableContent = {
-      columns: reportOverviewTableHeaders,
-      rows: categories.map(({ title, refs, score }) => ({
-        // The heading "ID" is inferred from the heading text in Markdown.
-        category: link5(`#${slugify(title)}`, title),
-        score: `${scoreMarker(score)}${SPACE}${boldMd2(
-          formatReportScore(score)
-        )}`,
-        audits: countCategoryAudits(refs, plugins).toString()
-      }))
-    };
-    return tableSection(tableContent);
-  }
-  return "";
-}
-function categoriesDetailsSection(report) {
-  const { categories, plugins } = report;
-  const categoryDetails = categories.flatMap((category) => {
-    const categoryTitle = h32(category.title);
-    const categoryScore = `${scoreMarker(
-      category.score
-    )}${SPACE}Score:  ${boldMd2(formatReportScore(category.score))}`;
-    const categoryMDItems = category.refs.map((ref) => {
-      if (ref.type === "group") {
-        const group = getSortableGroupByRef(ref, plugins);
-        const groupAudits = group.refs.map(
-          (groupRef) => getSortableAuditByRef(
-            { ...groupRef, plugin: group.plugin, type: "audit" },
-            plugins
-          )
-        );
-        const pluginTitle = getPluginNameFromSlug(ref.plugin, plugins);
-        return categoryGroupItem(group, groupAudits, pluginTitle);
-      } else {
-        const audit = getSortableAuditByRef(ref, plugins);
-        const pluginTitle = getPluginNameFromSlug(ref.plugin, plugins);
-        return categoryRef(audit, pluginTitle);
-      }
-    });
-    return section3(
-      categoryTitle,
-      metaDescription(category),
-      categoryScore,
-      ...categoryMDItems
-    );
-  });
-  return lines3(h22(CATEGORIES_TITLE), ...categoryDetails);
+function categoriesDetailsSection(report) {
+  const { categories, plugins } = report;
+  return new MarkdownDocument2().heading(HIERARCHY.level_2, "\u{1F3F7} Categories").$foreach(
+    categories,
+    (doc, category) => doc.heading(HIERARCHY.level_3, category.title).paragraph(metaDescription(category)).paragraph(
+      md3`${scoreMarker(category.score)} Score: ${md3.bold(
+        formatReportScore(category.score)
+      )}${binaryIconSuffix(category.score, category.isBinary)}`
+    ).list(
+      category.refs.map((ref) => {
+        if (ref.type === "group") {
+          const group = getSortableGroupByRef(ref, plugins);
+          const groupAudits = group.refs.map(
+            (groupRef) => getSortableAuditByRef(
+              { ...groupRef, plugin: group.plugin, type: "audit" },
+              plugins
+            )
+          );
+          const pluginTitle = getPluginNameFromSlug(ref.plugin, plugins);
+          return categoryGroupItem(group, groupAudits, pluginTitle);
+        } else {
+          const audit = getSortableAuditByRef(ref, plugins);
+          const pluginTitle = getPluginNameFromSlug(ref.plugin, plugins);
+          return categoryRef(audit, pluginTitle);
+        }
+      })
+    )
+  );
 }
 function categoryRef({ title, score, value, displayValue }, pluginTitle) {
-  const auditTitleAsLink = link5(
+  const auditTitleAsLink = md3.link(
     `#${slugify(title)}-${slugify(pluginTitle)}`,
     title
   );
   const marker = scoreMarker(score, "square");
-  return li2(
-    `${marker}${SPACE}${auditTitleAsLink}${SPACE}(_${pluginTitle}_) - ${boldMd2(
-      (displayValue || value).toString()
-    )}`
-  );
+  return md3`${marker} ${auditTitleAsLink} (${md3.italic(
+    pluginTitle
+  )}) - ${md3.bold((displayValue || value).toString())}`;
 }
 function categoryGroupItem({ score = 0, title }, groupAudits, pluginTitle) {
-  const groupTitle = li2(
-    `${scoreMarker(score)}${SPACE}${title}${SPACE}(_${pluginTitle}_)`
-  );
-  const auditTitles = groupAudits.map(
-    ({ title: auditTitle, score: auditScore, value, displayValue }) => {
-      const auditTitleLink = link5(
-        `#${slugify(auditTitle)}-${slugify(pluginTitle)}`,
-        auditTitle
-      );
-      const marker = scoreMarker(auditScore, "square");
-      return indentation2(
-        li2(
-          `${marker}${SPACE}${auditTitleLink} - ${boldMd2(
-            String(displayValue ?? value)
-          )}`
-        )
-      );
-    }
+  const groupTitle = md3`${scoreMarker(score)} ${title} (${md3.italic(
+    pluginTitle
+  )})`;
+  const auditsList = md3.list(
+    groupAudits.map(
+      ({ title: auditTitle, score: auditScore, value, displayValue }) => {
+        const auditTitleLink = md3.link(
+          `#${slugify(auditTitle)}-${slugify(pluginTitle)}`,
+          auditTitle
+        );
+        const marker = scoreMarker(auditScore, "square");
+        return md3`${marker} ${auditTitleLink} - ${md3.bold(
+          String(displayValue ?? value)
+        )}`;
+      }
+    )
   );
-  return lines3(groupTitle, ...auditTitles);
+  return md3`${groupTitle}${auditsList}`;
+}
+function binaryIconSuffix(score, isBinary) {
+  return targetScoreIcon(score, isBinary ? 1 : void 0, { prefix: " " });
 }
 
 // packages/utils/src/lib/reports/generate-md-report.ts
-var { h1: h12, h2: h23, h3: h33, lines: lines4, link: link6, section: section4, code: codeMd } = md;
-var { bold: boldHtml, details: details2 } = html;
 function auditDetailsAuditValue({
   score,
   value,
   displayValue
 }) {
-  return `${scoreMarker(score, "square")} ${boldHtml(
+  return md4`${scoreMarker(score, "square")} ${md4.bold(
     String(displayValue ?? value)
   )} (score: ${formatReportScore(score)})`;
 }
 function generateMdReport(report) {
-  const printCategories = report.categories.length > 0;
-  return lines4(
-    h12(reportHeadlineText),
-    printCategories ? categoriesOverviewSection(report) : "",
-    printCategories ? categoriesDetailsSection(report) : "",
-    auditsSection(report),
-    aboutSection(report),
-    `${FOOTER_PREFIX}${SPACE}${link6(README_LINK, "Code PushUp")}`
-  );
-}
-function auditDetailsIssues(issues = []) {
-  if (issues.length === 0) {
-    return "";
-  }
-  const detailsTableData = {
-    title: "Issues",
-    columns: issuesTableHeadings,
-    rows: issues.map(
-      ({ severity: severityVal, message, source: sourceVal }) => {
-        const severity = `${severityMarker(severityVal)} <i>${severityVal}</i>`;
-        if (!sourceVal) {
-          return { severity, message, file: "", line: "" };
-        }
-        const file = `<code>${sourceVal.file}</code>`;
-        if (!sourceVal.position) {
-          return { severity, message, file, line: "" };
-        }
-        const { startLine, endLine } = sourceVal.position;
-        const line = `${startLine || ""}${endLine && startLine !== endLine ? `-${endLine}` : ""}`;
-        return { severity, message, file, line };
-      }
-    )
-  };
-  return tableSection(detailsTableData);
-}
-function auditDetails(audit) {
-  const { table: table5, issues = [] } = audit.details ?? {};
-  const detailsValue = auditDetailsAuditValue(audit);
-  if (issues.length === 0 && table5 == null) {
-    return section4(detailsValue);
-  }
-  const tableSectionContent = table5 == null ? "" : tableSection(table5);
-  const issuesSectionContent = issues.length > 0 ? auditDetailsIssues(issues) : "";
-  return details2(
-    detailsValue,
-    lines4(tableSectionContent, issuesSectionContent)
-  );
-}
-function auditsSection({
-  plugins
-}) {
-  const content = plugins.flatMap(
-    ({ slug, audits }) => audits.flatMap((audit) => {
-      const auditTitle = `${audit.title}${SPACE}(${getPluginNameFromSlug(
-        slug,
-        plugins
-      )})`;
-      const detailsContent = auditDetails(audit);
-      const descriptionContent = metaDescription(audit);
-      return [h33(auditTitle), detailsContent, descriptionContent];
-    })
-  );
-  return section4(h23("\u{1F6E1}\uFE0F Audits"), ...content);
-}
-function aboutSection(report) {
-  const { date, plugins } = report;
-  const reportMetaTable = reportMetaData(report);
-  const pluginMetaTable = reportPluginMeta({ plugins });
-  return lines4(
-    h23("About"),
-    section4(
-      `Report was created by [Code PushUp](${README_LINK}) on ${formatDate(
-        new Date(date)
-      )}.`
-    ),
-    tableSection(pluginMetaTable),
-    tableSection(reportMetaTable)
-  );
-}
-function reportPluginMeta({ plugins }) {
-  return {
-    columns: [
-      {
-        key: "plugin",
-        align: "left"
-      },
-      {
-        key: "audits"
-      },
-      {
-        key: "version"
-      },
-      {
-        key: "duration"
-      }
-    ],
-    rows: plugins.map(
-      ({
-        title: pluginTitle,
-        audits,
-        version: pluginVersion,
-        duration: pluginDuration
-      }) => ({
-        plugin: pluginTitle,
-        audits: audits.length.toString(),
-        version: codeMd(pluginVersion || ""),
-        duration: formatDuration(pluginDuration)
-      })
+  return new MarkdownDocument3().heading(HIERARCHY.level_1, REPORT_HEADLINE_TEXT).$if(
+    report.categories.length > 0,
+    (doc) => doc.$concat(
+      categoriesOverviewSection(report),
+      categoriesDetailsSection(report)
     )
-  };
-}
-function reportMetaData({
-  commit,
-  version: version2,
-  duration,
-  plugins,
-  categories
-}) {
-  const commitInfo = commit ? `${commit.message}${SPACE}(${commit.hash})` : "N/A";
-  return {
-    columns: [
-      {
-        key: "commit",
-        align: "left"
-      },
-      {
-        key: "version"
-      },
-      {
-        key: "duration"
-      },
-      {
-        key: "plugins"
-      },
-      {
-        key: "categories"
-      },
-      {
-        key: "audits"
-      }
-    ],
-    rows: [
-      {
-        commit: commitInfo,
-        version: codeMd(version2 || ""),
-        duration: formatDuration(duration),
-        plugins: plugins.length,
-        categories: categories.length,
-        audits: plugins.reduce((acc, { audits }) => acc + audits.length, 0).toString()
-      }
-    ]
-  };
-}
-
-// packages/utils/src/lib/reports/generate-md-reports-diff.ts
-var {
-  h1: h13,
-  h2: h24,
-  lines: lines5,
-  link: link7,
-  bold: boldMd3,
-  italic: italicMd,
-  table: table4,
-  section: section5
-} = md;
-var { details: details3 } = html;
-var MAX_ROWS = 100;
-function generateMdReportsDiff(diff) {
-  return lines5(
-    section5(formatDiffHeaderSection(diff)),
-    formatDiffCategoriesSection(diff),
-    formatDiffGroupsSection(diff),
-    formatDiffAuditsSection(diff)
-  );
-}
-function formatDiffHeaderSection(diff) {
-  const outcomeTexts = {
-    positive: `\u{1F973} Code PushUp report has ${boldMd3("improved")}`,
-    negative: `\u{1F61F} Code PushUp report has ${boldMd3("regressed")}`,
-    mixed: `\u{1F928} Code PushUp report has both ${boldMd3(
-      "improvements and regressions"
-    )}`,
-    unchanged: `\u{1F610} Code PushUp report is ${boldMd3("unchanged")}`
-  };
-  const outcome = mergeDiffOutcomes(
-    changesToDiffOutcomes([
-      ...diff.categories.changed,
-      ...diff.groups.changed,
-      ...diff.audits.changed
-    ])
-  );
-  const styleCommits = (commits) => `compared target commit ${commits.after.hash} with source commit ${commits.before.hash}`;
-  return lines5(
-    h13("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 "";
-  }
-  const columns = [
-    { key: "category", label: "\u{1F3F7}\uFE0F Category", align: "left" },
-    { key: "before", label: hasChanges ? "\u2B50 Previous score" : "\u2B50 Score" },
-    { key: "after", label: "\u2B50 Current score" },
-    { key: "change", label: "\u{1F504} Score change" }
-  ];
-  return lines5(
-    h24("\u{1F3F7}\uFE0F Categories"),
-    categoriesCount > 0 && table4({
-      columns: hasChanges ? columns : columns.slice(0, 2),
-      rows: [
-        ...sortChanges(changed).map((category) => ({
-          category: formatTitle(category),
-          after: formatScoreWithColor(category.scores.after),
-          before: formatScoreWithColor(category.scores.before, {
-            skipBold: true
-          }),
-          change: formatScoreChange(category.scores.diff)
-        })),
-        ...added.map((category) => ({
-          category: formatTitle(category),
-          after: formatScoreWithColor(category.score),
-          before: italicMd("n/a (\\*)"),
-          change: italicMd("n/a (\\*)")
-        })),
-        ...unchanged.map((category) => ({
-          category: formatTitle(category),
-          after: formatScoreWithColor(category.score),
-          before: formatScoreWithColor(category.score, { skipBold: true }),
-          change: "\u2013"
-        }))
-      ].map(
-        (row) => hasChanges ? row : { category: row.category, before: row.before }
-      )
-    }),
-    added.length > 0 && section5(italicMd("(\\*) New category."))
-  );
-}
-function formatDiffGroupsSection(diff) {
-  if (diff.groups.changed.length + diff.groups.unchanged.length === 0) {
-    return "";
-  }
-  return lines5(
-    h24("\u{1F5C3}\uFE0F Groups"),
-    formatGroupsOrAuditsDetails("group", diff.groups, {
-      columns: [
-        { key: "plugin", label: "\u{1F50C} Plugin", align: "left" },
-        { key: "group", label: "\u{1F5C3}\uFE0F Group", align: "left" },
-        { key: "before", label: "\u2B50 Previous score" },
-        { key: "after", label: "\u2B50 Current score" },
-        { key: "change", label: "\u{1F504} Score change" }
-      ],
-      rows: sortChanges(diff.groups.changed).map((group) => ({
-        plugin: formatTitle(group.plugin),
-        group: formatTitle(group),
-        after: formatScoreWithColor(group.scores.after),
-        before: formatScoreWithColor(group.scores.before, { skipBold: true }),
-        change: formatScoreChange(group.scores.diff)
-      }))
+  ).$concat(auditsSection(report), aboutSection(report)).rule().paragraph(md4`${FOOTER_PREFIX} ${md4.link(README_LINK, "Code PushUp")}`).toString();
+}
+function auditDetailsIssues(issues = []) {
+  if (issues.length === 0) {
+    return null;
+  }
+  return new MarkdownDocument3().heading(HIERARCHY.level_4, "Issues").table(
+    [
+      { heading: "Severity", alignment: "center" },
+      { heading: "Message", alignment: "left" },
+      { heading: "Source file", alignment: "left" },
+      { heading: "Line(s)", alignment: "center" }
+    ],
+    issues.map(({ severity: level, message, source }) => {
+      const severity = md4`${severityMarker(level)} ${md4.italic(level)}`;
+      if (!source) {
+        return [severity, message];
+      }
+      const file = md4.code(source.file);
+      if (!source.position) {
+        return [severity, message, file];
+      }
+      const { startLine, endLine } = source.position;
+      const line = `${startLine || ""}${endLine && startLine !== endLine ? `-${endLine}` : ""}`;
+      return [severity, message, file, line];
     })
   );
 }
-function formatDiffAuditsSection(diff) {
-  return lines5(
-    h24("\u{1F6E1}\uFE0F Audits"),
-    formatGroupsOrAuditsDetails("audit", diff.audits, {
-      columns: [
-        { key: "plugin", label: "\u{1F50C} Plugin", align: "left" },
-        { key: "audit", label: "\u{1F6E1}\uFE0F Audit", align: "left" },
-        { key: "before", label: "\u{1F4CF} Previous value" },
-        { key: "after", label: "\u{1F4CF} Current value" },
-        { key: "change", label: "\u{1F504} Value change" }
-      ],
-      rows: sortChanges(diff.audits.changed).map((audit) => ({
-        plugin: formatTitle(audit.plugin),
-        audit: formatTitle(audit),
-        after: `${scoreMarker(audit.scores.after, "square")} ${boldMd3(
-          audit.displayValues.after || audit.values.after.toString()
-        )}`,
-        before: `${scoreMarker(audit.scores.before, "square")} ${audit.displayValues.before || audit.values.before.toString()}`,
-        change: formatValueChange(audit)
-      }))
-    })
+function auditDetails(audit) {
+  const { table: table2, issues = [] } = audit.details ?? {};
+  const detailsValue = auditDetailsAuditValue(audit);
+  if (issues.length === 0 && !table2?.rows.length) {
+    return new MarkdownDocument3().paragraph(detailsValue);
+  }
+  const tableSectionContent = table2 && tableSection(table2);
+  const issuesSectionContent = issues.length > 0 && auditDetailsIssues(issues);
+  return new MarkdownDocument3().details(
+    detailsValue,
+    new MarkdownDocument3().$concat(tableSectionContent, issuesSectionContent)
   );
 }
-function formatGroupsOrAuditsDetails(token, { changed, unchanged }, tableData) {
-  return changed.length === 0 ? summarizeUnchanged(token, { changed, unchanged }) : details3(
-    summarizeDiffOutcomes(changesToDiffOutcomes(changed), token),
-    lines5(
-      table4({
-        ...tableData,
-        rows: tableData.rows.slice(0, MAX_ROWS)
-        // use never to avoid typing problem
-      }),
-      changed.length > MAX_ROWS && italicMd(
-        `Only the ${MAX_ROWS} most affected ${pluralize(
-          token
-        )} are listed above for brevity.`
-      ),
-      unchanged.length > 0 && summarizeUnchanged(token, { changed, unchanged })
-    )
+function auditsSection({
+  plugins
+}) {
+  return new MarkdownDocument3().heading(HIERARCHY.level_2, "\u{1F6E1}\uFE0F Audits").$foreach(
+    plugins.flatMap(
+      (plugin) => plugin.audits.map((audit) => ({ ...audit, plugin }))
+    ),
+    (doc, { plugin, ...audit }) => {
+      const auditTitle = `${audit.title} (${plugin.title})`;
+      const detailsContent = auditDetails(audit);
+      const descriptionContent = metaDescription(audit);
+      return doc.heading(HIERARCHY.level_3, auditTitle).$concat(detailsContent).paragraph(descriptionContent);
+    }
   );
 }
-function formatScoreChange(diff) {
-  const marker = getDiffMarker(diff);
-  const text = formatDiffNumber(Math.round(diff * 1e3) / 10);
-  return colorByScoreDiff(`${marker} ${text}`, diff);
+function aboutSection(report) {
+  const { date, plugins } = report;
+  return new MarkdownDocument3().heading(HIERARCHY.level_2, "About").paragraph(
+    md4`Report was created by ${md4.link(
+      README_LINK,
+      "Code PushUp"
+    )} on ${formatDate(new Date(date))}.`
+  ).table(...pluginMetaTable({ plugins })).table(...reportMetaTable(report));
+}
+function pluginMetaTable({
+  plugins
+}) {
+  return [
+    [
+      { heading: "Plugin", alignment: "left" },
+      { heading: "Audits", alignment: "center" },
+      { heading: "Version", alignment: "center" },
+      { heading: "Duration", alignment: "right" }
+    ],
+    plugins.map(({ title, audits, version: version3 = "", duration }) => [
+      title,
+      audits.length.toString(),
+      version3 && md4.code(version3),
+      formatDuration(duration)
+    ])
+  ];
 }
-function formatValueChange({
-  values,
-  scores
+function reportMetaTable({
+  commit,
+  version: version3,
+  duration,
+  plugins,
+  categories
 }) {
-  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);
+  return [
+    [
+      { heading: "Commit", alignment: "left" },
+      { heading: "Version", alignment: "center" },
+      { heading: "Duration", alignment: "right" },
+      { heading: "Plugins", alignment: "center" },
+      { heading: "Categories", alignment: "center" },
+      { heading: "Audits", alignment: "center" }
+    ],
+    [
+      [
+        commit ? `${commit.message} (${commit.hash})` : "N/A",
+        md4.code(version3),
+        formatDuration(duration),
+        plugins.length.toString(),
+        categories.length.toString(),
+        plugins.reduce((acc, { audits }) => acc + audits.length, 0).toString()
+      ]
+    ]
+  ];
 }
+
+// packages/utils/src/lib/reports/generate-md-reports-diff.ts
+import {
+  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 summarizeUnchanged(token, { changed, unchanged }) {
-  return section5(
-    [
-      changed.length > 0 ? pluralizeToken(`other ${token}`, unchanged.length) : `All of ${pluralizeToken(token, unchanged.length)}`,
-      unchanged.length === 1 ? "is" : "are",
-      "unchanged."
-    ].join(" ")
-  );
+  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(
@@ -2281,20 +1984,46 @@ function summarizeDiffOutcomes(outcomes, token) {
     }
   }).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 link7(docsUrl, title);
+    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) {
@@ -2329,9 +2058,218 @@ function countDiffOutcomes(outcomes) {
     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")}`,
+    mixed: md5`🤨 Code PushUp report has both ${md5.bold(
+      "improvements and regressions"
+    )}`,
+    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(toArray(diff).flatMap(getDiffChanges))
+  );
+  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, 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" },
+    {
+      heading: hasChanges ? "\u2B50 Previous score" : "\u2B50 Score",
+      alignment: "center"
+    },
+    { heading: "\u2B50 Current score", alignment: "center" },
+    { heading: "\u{1F504} Score change", alignment: "center" }
+  ];
+  const rows = [
+    ...sortChanges(changed).map((category) => [
+      formatTitle(category),
+      formatScoreWithColor(category.scores.before, {
+        skipBold: true
+      }),
+      formatScoreWithColor(category.scores.after),
+      formatScoreChange(category.scores.diff)
+    ]),
+    ...added.map((category) => [
+      formatTitle(category),
+      md6.italic("n/a (\\*)"),
+      formatScoreWithColor(category.score),
+      md6.italic("n/a (\\*)")
+    ]),
+    ...skipUnchanged ? [] : unchanged.map((category) => [
+      formatTitle(category),
+      formatScoreWithColor(category.score, { skipBold: true }),
+      formatScoreWithColor(category.score),
+      "\u2013"
+    ])
+  ];
+  return [
+    hasChanges ? columns : columns.slice(0, 2),
+    rows.map((row) => hasChanges ? row : row.slice(0, 2))
+  ];
+}
+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, level) {
+  if (diff.groups.changed.length + diff.groups.unchanged.length === 0) {
+    return null;
+  }
+  return new MarkdownDocument5().heading(level, "\u{1F5C3}\uFE0F Groups").$concat(
+    createGroupsOrAuditsDetails(
+      "group",
+      diff.groups,
+      [
+        { heading: "\u{1F50C} Plugin", alignment: "left" },
+        { heading: "\u{1F5C3}\uFE0F Group", alignment: "left" },
+        { heading: "\u2B50 Previous score", alignment: "center" },
+        { heading: "\u2B50 Current score", alignment: "center" },
+        { heading: "\u{1F504} Score change", alignment: "center" }
+      ],
+      sortChanges(diff.groups.changed).map((group) => [
+        formatTitle(group.plugin),
+        formatTitle(group),
+        formatScoreWithColor(group.scores.before, { skipBold: true }),
+        formatScoreWithColor(group.scores.after),
+        formatScoreChange(group.scores.diff)
+      ])
+    )
+  );
+}
+function createDiffAuditsSection(diff, level) {
+  return new MarkdownDocument5().heading(level, "\u{1F6E1}\uFE0F Audits").$concat(
+    createGroupsOrAuditsDetails(
+      "audit",
+      diff.audits,
+      [
+        { heading: "\u{1F50C} Plugin", alignment: "left" },
+        { heading: "\u{1F6E1}\uFE0F Audit", alignment: "left" },
+        { heading: "\u{1F4CF} Previous value", alignment: "center" },
+        { heading: "\u{1F4CF} Current value", alignment: "center" },
+        { heading: "\u{1F504} Value change", alignment: "center" }
+      ],
+      sortChanges(diff.audits.changed).map((audit) => [
+        formatTitle(audit.plugin),
+        formatTitle(audit),
+        `${scoreMarker(audit.scores.before, "square")} ${audit.displayValues.before || audit.values.before.toString()}`,
+        md6`${scoreMarker(audit.scores.after, "square")} ${md6.bold(
+          audit.displayValues.after || audit.values.after.toString()
+        )}`,
+        formatValueChange(audit)
+      ])
+    )
+  );
+}
+
+// packages/utils/src/lib/reports/load-report.ts
+import { join as join2 } from "node:path";
+async function loadReport(options2) {
+  const { outputDir, filename, format } = options2;
+  await ensureDirectoryExists(outputDir);
+  const filePath = join2(outputDir, `${filename}.${format}`);
+  if (format === "json") {
+    const content = await readJsonFile(filePath);
+    return reportSchema.parse(content);
+  }
+  const text = await readTextFile(filePath);
+  return text;
+}
 
 // packages/utils/src/lib/reports/log-stdout-summary.ts
-import chalk4 from "chalk";
+import { bold as bold4, cyan, cyanBright, green as green2, red } from "ansis";
 function log(msg = "") {
   ui().logger.log(msg);
 }
@@ -2347,15 +2285,15 @@ function logStdoutSummary(report) {
   log();
 }
 function reportToHeaderSection(report) {
-  const { packageName, version: version2 } = report;
-  return `${chalk4.bold(reportHeadlineText)} - ${packageName}@${version2}`;
+  const { packageName, version: version3 } = report;
+  return `${bold4(REPORT_HEADLINE_TEXT)} - ${packageName}@${version3}`;
 }
 function logPlugins(report) {
   const { plugins } = report;
   plugins.forEach((plugin) => {
     const { title, audits } = plugin;
     log();
-    log(chalk4.magentaBright.bold(`${title} audits`));
+    log(bold4.magentaBright(`${title} audits`));
     log();
     audits.forEach((audit) => {
       ui().row([
@@ -2370,8 +2308,9 @@ function logPlugins(report) {
           padding: [0, 3, 0, 0]
         },
         {
-          text: chalk4.cyanBright(audit.displayValue || `${audit.value}`),
-          width: 10,
+          text: cyanBright(audit.displayValue || `${audit.value}`),
+          // eslint-disable-next-line no-magic-numbers
+          width: 20,
           padding: [0, 0, 0, 0]
         }
       ]);
@@ -2381,42 +2320,38 @@ function logPlugins(report) {
 }
 function logCategories({ categories, plugins }) {
   const hAlign = (idx) => idx === 0 ? "left" : "right";
-  const rows = categories.map(({ title, score, refs }) => [
+  const rows = categories.map(({ title, score, refs, isBinary }) => [
     title,
-    applyScoreColor({ score }),
+    `${binaryIconPrefix(score, isBinary)}${applyScoreColor({ score })}`,
     countCategoryAudits(refs, plugins)
   ]);
-  const table5 = ui().table();
-  table5.columnWidths([TERMINAL_WIDTH - 9 - 10 - 4, 9, 10]);
-  table5.head(
-    reportRawOverviewTableHeaders.map((heading, idx) => ({
-      content: chalk4.cyan(heading),
+  const table2 = ui().table();
+  table2.columnWidths([TERMINAL_WIDTH - 9 - 10 - 4, 9, 10]);
+  table2.head(
+    REPORT_RAW_OVERVIEW_TABLE_HEADERS.map((heading, idx) => ({
+      content: cyan(heading),
       hAlign: hAlign(idx)
     }))
   );
   rows.forEach(
-    (row) => table5.row(
+    (row) => table2.row(
       row.map((content, idx) => ({
         content: content.toString(),
         hAlign: hAlign(idx)
       }))
     )
   );
-  log(chalk4.magentaBright.bold("Categories"));
+  log(bold4.magentaBright("Categories"));
   log();
-  table5.render();
+  table2.render();
   log();
 }
-function applyScoreColor({ score, text }) {
-  const formattedScore = text ?? formatReportScore(score);
-  const style = text ? chalk4 : chalk4.bold;
-  if (score >= SCORE_COLOR_RANGE.GREEN_MIN) {
-    return style.green(formattedScore);
-  }
-  if (score >= SCORE_COLOR_RANGE.YELLOW_MIN) {
-    return style.yellow(formattedScore);
-  }
-  return style.red(formattedScore);
+function binaryIconPrefix(score, isBinary) {
+  return targetScoreIcon(score, isBinary ? 1 : void 0, {
+    passIcon: bold4(green2("\u2713")),
+    failIcon: bold4(red("\u2717")),
+    postfix: " "
+  });
 }
 
 // packages/utils/src/lib/reports/scoring.ts
@@ -2506,56 +2441,6 @@ function parseScoringParameters(refs, scoreFn) {
   return scoredRefs;
 }
 
-// packages/utils/src/lib/reports/sorting.ts
-function sortReport(report) {
-  const { categories, plugins } = report;
-  const sortedCategories = categories.map((category) => {
-    const { audits, groups: groups2 } = category.refs.reduce(
-      (acc, ref) => ({
-        ...acc,
-        ...ref.type === "group" ? {
-          groups: [...acc.groups, getSortableGroupByRef(ref, plugins)]
-        } : {
-          audits: [...acc.audits, getSortableAuditByRef(ref, plugins)]
-        }
-      }),
-      { groups: [], audits: [] }
-    );
-    const sortedAuditsAndGroups = [...audits, ...groups2].sort(
-      compareCategoryAuditsAndGroups
-    );
-    const sortedRefs = [...category.refs].sort((a, b) => {
-      const aIndex = sortedAuditsAndGroups.findIndex(
-        (ref) => ref.slug === a.slug && ref.plugin === a.plugin
-      );
-      const bIndex = sortedAuditsAndGroups.findIndex(
-        (ref) => ref.slug === b.slug && ref.plugin === b.plugin
-      );
-      return aIndex - bIndex;
-    });
-    return { ...category, refs: sortedRefs };
-  });
-  return {
-    ...report,
-    categories: sortedCategories,
-    plugins: sortPlugins(plugins)
-  };
-}
-function sortPlugins(plugins) {
-  return plugins.map((plugin) => ({
-    ...plugin,
-    audits: [...plugin.audits].sort(compareAudits).map(
-      (audit) => audit.details?.issues ? {
-        ...audit,
-        details: {
-          ...audit.details,
-          issues: [...audit.details.issues].sort(compareIssues)
-        }
-      } : audit
-    )
-  }));
-}
-
 // packages/utils/src/lib/verbose-utils.ts
 function getLogVerbose(verbose = false) {
   return (msg) => {
@@ -2578,10 +2463,10 @@ var verboseUtils = (verbose = false) => ({
 
 // packages/core/package.json
 var name = "@code-pushup/core";
-var version = "0.48.0";
+var version = "0.50.0";
 
 // packages/core/src/lib/implementation/execute-plugin.ts
-import chalk5 from "chalk";
+import { bold as bold5 } from "ansis";
 
 // packages/core/src/lib/normalize.ts
 function normalizeIssue(issue, gitRoot) {
@@ -2644,7 +2529,7 @@ async function executeRunnerFunction(runner, onProgress) {
 var PluginOutputMissingAuditError = class extends Error {
   constructor(auditSlug) {
     super(
-      `Audit metadata not present in plugin config. Missing slug: ${chalk5.bold(
+      `Audit metadata not present in plugin config. Missing slug: ${bold5(
         auditSlug
       )}`
     );
@@ -2686,7 +2571,7 @@ async function executePlugin(pluginConfig, onProgress) {
   };
 }
 var wrapProgress = async (pluginCfg, steps, progressBar) => {
-  progressBar?.updateTitle(`Executing ${chalk5.bold(pluginCfg.title)}`);
+  progressBar?.updateTitle(`Executing ${bold5(pluginCfg.title)}`);
   try {
     const pluginReport = await executePlugin(pluginCfg);
     progressBar?.incrementInSteps(steps);
@@ -2694,7 +2579,7 @@ var wrapProgress = async (pluginCfg, steps, progressBar) => {
   } catch (error) {
     progressBar?.incrementInSteps(steps);
     throw new Error(
-      error instanceof Error ? `- Plugin ${chalk5.bold(pluginCfg.title)} (${chalk5.bold(
+      error instanceof Error ? `- Plugin ${bold5(pluginCfg.title)} (${bold5(
         pluginCfg.slug
       )}) produced the following error:
   - ${error.message}` : String(error)
@@ -2834,6 +2719,10 @@ async function collectAndPersistReports(options2) {
 // packages/core/src/lib/compare.ts
 import { writeFile as writeFile2 } from "node:fs/promises";
 import { join as join5 } from "node:path";
+import {
+  PortalOperationError,
+  getPortalComparisonLink
+} from "@code-pushup/portal-client";
 
 // packages/core/src/lib/implementation/compare-scorables.ts
 function compareCategories(reports) {
@@ -2970,7 +2859,7 @@ function selectMeta(meta) {
 }
 
 // packages/core/src/lib/compare.ts
-async function compareReportFiles(inputPaths, persistConfig) {
+async function compareReportFiles(inputPaths, persistConfig, uploadConfig, label) {
   const { outputDir, filename, format } = persistConfig;
   const [reportBefore, reportAfter] = await Promise.all([
     readJsonFile(inputPaths.before),
@@ -2980,11 +2869,20 @@ async function compareReportFiles(inputPaths, persistConfig) {
     before: reportSchema.parse(reportBefore),
     after: reportSchema.parse(reportAfter)
   };
-  const reportsDiff = compareReports(reports);
+  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);
+      const content = reportsDiffToFileContent(diff, fmt);
       await ensureDirectoryExists(outputDir);
       await writeFile2(outputPath, content);
       return outputPath;
@@ -3022,6 +2920,29 @@ function reportsDiffToFileContent(reportsDiff, format) {
       return generateMdReportsDiff(reportsDiff);
   }
 }
+async function fetchPortalComparisonLink(uploadConfig, commits) {
+  const { server, apiKey, organization, project } = uploadConfig;
+  try {
+    return await getPortalComparisonLink({
+      server,
+      apiKey,
+      parameters: {
+        organization,
+        project,
+        before: commits.before.hash,
+        after: commits.after.hash
+      }
+    });
+  } catch (error) {
+    if (error instanceof PortalOperationError) {
+      ui().logger.warning(
+        `Failed to fetch portal comparison link - ${error.message}`
+      );
+      return void 0;
+    }
+    throw error;
+  }
+}
 
 // packages/core/src/lib/upload.ts
 import {
@@ -3077,9 +2998,9 @@ function auditToGQL(audit) {
     score,
     value,
     displayValue: formattedValue,
-    details: details4
+    details: details2
   } = audit;
-  const { issues, table: table5 } = details4 ?? {};
+  const { issues, table: table2 } = details2 ?? {};
   return {
     slug,
     title,
@@ -3088,10 +3009,10 @@ function auditToGQL(audit) {
     score,
     value,
     formattedValue,
-    ...details4 && {
+    ...details2 && {
       details: {
         ...issues && { issues: issues.map(issueToGQL) },
-        ...table5 && { tables: [tableToGQL(table5)] }
+        ...table2 && { tables: [tableToGQL(table2)] }
       }
     }
   };
@@ -3110,11 +3031,11 @@ function issueToGQL(issue) {
     }
   };
 }
-function tableToGQL(table5) {
+function tableToGQL(table2) {
   return {
-    ...table5.title && { title: table5.title },
-    ...table5.columns?.length && {
-      columns: table5.columns.map(
+    ...table2.title && { title: table2.title },
+    ...table2.columns?.length && {
+      columns: table2.columns.map(
         (column) => typeof column === "string" ? { alignment: tableAlignmentToGQL(column) } : {
           key: column.key,
           label: column.label,
@@ -3122,7 +3043,7 @@ function tableToGQL(table5) {
         }
       )
     },
-    rows: table5.rows.map(
+    rows: table2.rows.map(
       (row) => Array.isArray(row) ? row.map((content) => ({ content: content?.toString() ?? "" })) : Object.entries(row).map(([key, content]) => ({
         key,
         content: content?.toString() ?? ""
@@ -3269,15 +3190,54 @@ 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";
 
 // packages/cli/src/lib/implementation/logging.ts
-import chalk6 from "chalk";
+import { bold as bold6, gray as gray3 } from "ansis";
 function renderConfigureCategoriesHint() {
   ui().logger.info(
-    chalk6.gray(
+    gray3(
       `\u{1F4A1} Configure categories to see the scores in an overview table. See: ${link(
         "https://github.com/code-pushup/cli/blob/main/packages/cli/README.md"
       )}`
@@ -3292,8 +3252,8 @@ function collectSuccessfulLog() {
   ui().logger.success("Collecting report successful!");
 }
 function renderIntegratePortalHint() {
-  ui().sticker().add(chalk6.bold(chalk6.gray("\u{1F4A1} Integrate the portal"))).add("").add(
-    `${chalk6.gray("\u276F")} Upload a report to the server - ${chalk6.gray(
+  ui().sticker().add(bold6.gray("\u{1F4A1} Integrate the portal")).add("").add(
+    `${gray3("\u276F")} Upload a report to the server - ${gray3(
       "npx code-pushup upload"
     )}`
   ).add(
@@ -3301,11 +3261,11 @@ function renderIntegratePortalHint() {
       "https://github.com/code-pushup/cli/tree/main/packages/cli#upload-command"
     )}`
   ).add(
-    `${chalk6.gray("\u276F")} ${chalk6.gray("Portal Integration")} - ${link(
+    `${gray3("\u276F")} ${gray3("Portal Integration")} - ${link(
       "https://github.com/code-pushup/cli/blob/main/packages/cli/README.md#portal-integration"
     )}`
   ).add(
-    `${chalk6.gray("\u276F")} ${chalk6.gray("Upload Command")} - ${link(
+    `${gray3("\u276F")} ${gray3("Upload Command")} - ${link(
       "https://github.com/code-pushup/cli/blob/main/packages/cli/README.md#portal-integration"
     )}`
   ).render();
@@ -3318,8 +3278,8 @@ function yargsAutorunCommandObject() {
     command: command2,
     describe: "Shortcut for running collect followed by upload",
     handler: async (args) => {
-      ui().logger.log(chalk7.bold(CLI_NAME));
-      ui().logger.info(chalk7.gray(`Run ${command2}...`));
+      ui().logger.log(bold7(CLI_NAME));
+      ui().logger.info(gray4(`Run ${command2}...`));
       const options2 = args;
       const optionsWithFormat = {
         ...options2,
@@ -3347,7 +3307,7 @@ function yargsAutorunCommandObject() {
 }
 
 // packages/cli/src/lib/collect/collect-command.ts
-import chalk8 from "chalk";
+import { bold as bold8, gray as gray5 } from "ansis";
 function yargsCollectCommandObject() {
   const command2 = "collect";
   return {
@@ -3355,8 +3315,8 @@ function yargsCollectCommandObject() {
     describe: "Run Plugins and collect results",
     handler: async (args) => {
       const options2 = args;
-      ui().logger.log(chalk8.bold(CLI_NAME));
-      ui().logger.info(chalk8.gray(`Run ${command2}...`));
+      ui().logger.log(bold8(CLI_NAME));
+      ui().logger.info(gray5(`Run ${command2}...`));
       await collectAndPersistReports(options2);
       collectSuccessfulLog();
       if (options2.categories.length === 0) {
@@ -3370,8 +3330,8 @@ function yargsCollectCommandObject() {
   };
 }
 function renderUploadAutorunHint() {
-  ui().sticker().add(chalk8.bold(chalk8.gray("\u{1F4A1} Visualize your reports"))).add("").add(
-    `${chalk8.gray("\u276F")} npx code-pushup upload - ${chalk8.gray(
+  ui().sticker().add(bold8.gray("\u{1F4A1} Visualize your reports")).add("").add(
+    `${gray5("\u276F")} npx code-pushup upload - ${gray5(
       "Run upload to upload the created report to the server"
     )}`
   ).add(
@@ -3379,9 +3339,7 @@ function renderUploadAutorunHint() {
       "https://github.com/code-pushup/cli/tree/main/packages/cli#upload-command"
     )}`
   ).add(
-    `${chalk8.gray("\u276F")} npx code-pushup autorun - ${chalk8.gray(
-      "Run collect & upload"
-    )}`
+    `${gray5("\u276F")} npx code-pushup autorun - ${gray5("Run collect & upload")}`
   ).add(
     `  ${link(
       "https://github.com/code-pushup/cli/tree/main/packages/cli#autorun-command"
@@ -3390,7 +3348,7 @@ function renderUploadAutorunHint() {
 }
 
 // packages/cli/src/lib/compare/compare-command.ts
-import chalk9 from "chalk";
+import { bold as bold9, gray as gray6 } from "ansis";
 
 // packages/cli/src/lib/implementation/compare.options.ts
 function yargsCompareOptionsDefinition() {
@@ -3404,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"
     }
   };
 }
@@ -3416,20 +3378,25 @@ function yargsCompareCommandObject() {
     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 ${command2}...`));
+      ui().logger.log(bold9(CLI_NAME));
+      ui().logger.info(gray6(`Run ${command2}...`));
       const options2 = args;
-      const { before, after, persist } = options2;
-      const outputPaths = await compareReportFiles({ before, after }, persist);
+      const { before, after, label, persist, upload: upload2 } = options2;
+      const outputPaths = await compareReportFiles(
+        { before, after },
+        persist,
+        upload2,
+        label
+      );
       ui().logger.info(
-        `Reports diff written to ${outputPaths.map((path) => chalk9.bold(path)).join(" and ")}`
+        `Reports diff written to ${outputPaths.map((path) => bold9(path)).join(" and ")}`
       );
     }
   };
 }
 
 // packages/cli/src/lib/history/history-command.ts
-import chalk10 from "chalk";
+import { bold as bold10, gray as gray7 } from "ansis";
 
 // packages/cli/src/lib/implementation/global.utils.ts
 function filterKebabCaseKeys(obj) {
@@ -3555,8 +3522,8 @@ async function normalizeHashOptions(processArgs) {
 // packages/cli/src/lib/history/history-command.ts
 var command = "history";
 async function handler(args) {
-  ui().logger.info(chalk10.bold(CLI_NAME));
-  ui().logger.info(chalk10.gray(`Run ${command}`));
+  ui().logger.info(bold10(CLI_NAME));
+  ui().logger.info(gray7(`Run ${command}`));
   const currentBranch = await getCurrentBranchOrTag();
   const { targetBranch: rawTargetBranch, ...opt } = args;
   const {
@@ -3605,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";
@@ -3620,15 +3619,15 @@ function yargsConfigCommandObject() {
 }
 
 // packages/cli/src/lib/upload/upload-command.ts
-import chalk11 from "chalk";
+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(chalk11.bold(CLI_NAME));
-      ui().logger.info(chalk11.gray(`Run ${command2}...`));
+      ui().logger.log(bold12(CLI_NAME));
+      ui().logger.info(gray9(`Run ${command2}...`));
       const options2 = args;
       if (options2.upload == null) {
         renderIntegratePortalHint();
@@ -3651,7 +3650,8 @@ var commands = [
   yargsUploadCommandObject(),
   yargsHistoryCommandObject(),
   yargsCompareCommandObject(),
-  yargsConfigCommandObject()
+  yargsConfigCommandObject(),
+  yargsMergeDiffsCommandObject()
 ];
 
 // packages/cli/src/lib/implementation/core-config.middleware.ts
@@ -3679,7 +3679,9 @@ async function coreConfigMiddleware(processArgs) {
     persist: {
       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
+      format: normalizeFormats(
+        cliPersist?.format ?? rcPersist?.format ?? DEFAULT_PERSIST_FORMAT
+      )
     },
     ...upload2 != null && { upload: upload2 },
     categories: rcCategories ?? [],
@@ -3687,9 +3689,10 @@ async function coreConfigMiddleware(processArgs) {
     ...remainingCliOptions
   };
 }
+var normalizeFormats = (formats) => (formats ?? []).flatMap((format) => format.split(","));
 
 // packages/cli/src/lib/implementation/validate-plugin-filter-options.utils.ts
-import chalk12 from "chalk";
+import { yellow } from "ansis";
 function validatePluginFilterOption(filterOption, {
   plugins,
   categories
@@ -3705,7 +3708,7 @@ function validatePluginFilterOption(filterOption, {
   const filterFunction = (plugin) => isSkipOption ? pluginsToFilterSet.has(plugin) : !pluginsToFilterSet.has(plugin);
   if (missingPlugins.length > 0 && verbose) {
     ui().logger.info(
-      `${chalk12.yellow(
+      `${yellow(
         "\u26A0"
       )} The --${filterOption} argument references plugins with "${missingPlugins.join(
         '", "'
@@ -3860,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: {
@@ -3888,8 +3891,55 @@ var groups = {
 };
 
 // packages/cli/src/lib/yargs-cli.ts
-import chalk13 from "chalk";
+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 ?? [];
@@ -3898,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({
@@ -3906,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(chalk13.bold(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(
@@ -3926,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);
@@ -3942,7 +3997,7 @@ function yargsCli(argv, cfg) {
 function validatePersistFormat(persist) {
   try {
     if (persist.format != null) {
-      persist.format.forEach((format) => formatSchema.parse(format));
+      persist.format.flatMap((format) => format.split(",")).forEach((format) => formatSchema.parse(format));
     }
     return true;
   } catch {
@@ -3978,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",