feat(cli,core,utils): include optional link to portal in markdown comment

package.json

@@ -47,7 +47,7 @@
     "node": ">=18.16"
   },
   "dependencies": {
-    "@code-pushup/portal-client": "^0.8.0",
+    "@code-pushup/portal-client": "^0.9.0",
     "@isaacs/cliui": "^8.0.2",
     "@nx/devkit": "17.3.2",
     "@poppinss/cliui": "^6.4.0",

packages/cli/src/lib/compare/compare-command.ts

@@ -1,10 +1,10 @@
 import { bold, gray } from 'ansis';
 import { CommandModule } from 'yargs';
 import { compareReportFiles } from '@code-pushup/core';
-import { PersistConfig } from '@code-pushup/models';
+import { PersistConfig, UploadConfig } from '@code-pushup/models';
 import { ui } from '@code-pushup/utils';
 import { CLI_NAME } from '../constants';
-import type { CompareOptions } from '../implementation/compare.model';
+import { CompareOptions } from '../implementation/compare.model';
 import { yargsCompareOptionsDefinition } from '../implementation/compare.options';
 
 export function yargsCompareCommandObject() {
@@ -19,11 +19,16 @@ export function yargsCompareCommandObject() {
 
       const options = args as CompareOptions & {
         persist: Required<PersistConfig>;
+        upload?: UploadConfig;
       };
 
-      const { before, after, persist } = options;
+      const { before, after, persist, upload } = options;
 
-      const outputPaths = await compareReportFiles({ before, after }, persist);
+      const outputPaths = await compareReportFiles(
+        { before, after },
+        persist,
+        upload,
+      );
 
       ui().logger.info(
         `Reports diff written to ${outputPaths

packages/cli/src/lib/compare/compare-command.unit.test.ts

@@ -43,6 +43,7 @@ describe('compare-command', () => {
         filename: DEFAULT_PERSIST_FILENAME,
         format: DEFAULT_PERSIST_FORMAT,
       },
+      expect.any(Object),
     );
   });
 

packages/core/package.json

@@ -5,7 +5,7 @@
   "dependencies": {
     "@code-pushup/models": "0.48.0",
     "@code-pushup/utils": "0.48.0",
-    "@code-pushup/portal-client": "^0.8.0",
+    "@code-pushup/portal-client": "^0.9.0",
     "ansis": "^3.3.0"
   },
   "type": "commonjs",

packages/core/src/lib/compare.ts

@@ -1,10 +1,15 @@
 import { writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import {
+  PortalOperationError,
+  getPortalComparisonLink,
+} from '@code-pushup/portal-client';
 import {
   type Format,
   type PersistConfig,
   Report,
   ReportsDiff,
+  type UploadConfig,
   reportSchema,
 } from '@code-pushup/models';
 import {
@@ -14,6 +19,7 @@ import {
   generateMdReportsDiff,
   readJsonFile,
   scoreReport,
+  ui,
 } from '@code-pushup/utils';
 import { name as packageName, version } from '../../package.json';
 import {
@@ -26,6 +32,7 @@ import {
 export async function compareReportFiles(
   inputPaths: Diff<string>,
   persistConfig: Required<PersistConfig>,
+  uploadConfig: UploadConfig | undefined,
 ): Promise<string[]> {
   const { outputDir, filename, format } = persistConfig;
 
@@ -40,10 +47,15 @@ export async function compareReportFiles(
 
   const reportsDiff = compareReports(reports);
 
+  const portalUrl =
+    uploadConfig && reportsDiff.commits && format.includes('md')
+      ? await fetchPortalComparisonLink(uploadConfig, reportsDiff.commits)
+      : undefined;
+
   return Promise.all(
     format.map(async fmt => {
       const outputPath = join(outputDir, `${filename}-diff.${fmt}`);
-      const content = reportsDiffToFileContent(reportsDiff, fmt);
+      const content = reportsDiffToFileContent(reportsDiff, fmt, portalUrl);
       await ensureDirectoryExists(outputDir);
       await writeFile(outputPath, content);
       return outputPath;
@@ -86,11 +98,39 @@ export function compareReports(reports: Diff<Report>): ReportsDiff {
 function reportsDiffToFileContent(
   reportsDiff: ReportsDiff,
   format: Format,
+  portalUrl: string | undefined,
 ): string {
   switch (format) {
     case 'json':
       return JSON.stringify(reportsDiff, null, 2);
     case 'md':
-      return generateMdReportsDiff(reportsDiff);
+      return generateMdReportsDiff(reportsDiff, portalUrl ?? undefined);
+  }
+}
+
+async function fetchPortalComparisonLink(
+  uploadConfig: UploadConfig,
+  commits: NonNullable<ReportsDiff['commits']>,
+): Promise<string | undefined> {
+  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 undefined;
+    }
+    throw error;
   }
 }

packages/core/src/lib/compare.unit.test.ts

@@ -1,5 +1,7 @@
 import { vol } from 'memfs';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { getPortalComparisonLink } from '@code-pushup/portal-client';
 import { Commit, Report, reportsDiffSchema } from '@code-pushup/models';
 import {
   COMMIT_ALT_MOCK,
@@ -13,6 +15,11 @@ import { Diff, fileExists, readJsonFile } from '@code-pushup/utils';
 import { compareReportFiles, compareReports } from './compare';
 
 describe('compareReportFiles', () => {
+  const commitShas = {
+    before: MINIMAL_REPORT_MOCK.commit!.hash,
+    after: REPORT_MOCK.commit!.hash,
+  };
+
   beforeEach(() => {
     vol.fromJSON(
       {
@@ -30,6 +37,7 @@ describe('compareReportFiles', () => {
         after: join(MEMFS_VOLUME, 'target-report.json'),
       },
       { outputDir: MEMFS_VOLUME, filename: 'report', format: ['json'] },
+      undefined,
     );
 
     const reportsDiffPromise = readJsonFile(
@@ -48,6 +56,7 @@ describe('compareReportFiles', () => {
         after: join(MEMFS_VOLUME, 'target-report.json'),
       },
       { outputDir: MEMFS_VOLUME, filename: 'report', format: ['json', 'md'] },
+      undefined,
     );
 
     await expect(
@@ -57,6 +66,116 @@ describe('compareReportFiles', () => {
       fileExists(join(MEMFS_VOLUME, 'report-diff.md')),
     ).resolves.toBeTruthy();
   });
+
+  it('should include portal link (fetched using upload config) in Markdown file', async () => {
+    await compareReportFiles(
+      {
+        before: join(MEMFS_VOLUME, 'source-report.json'),
+        after: join(MEMFS_VOLUME, 'target-report.json'),
+      },
+      { outputDir: MEMFS_VOLUME, filename: 'report', format: ['json', 'md'] },
+      {
+        server: 'https://api.code-pushup.dev/graphql',
+        apiKey: 'cp_XXXXX',
+        organization: 'dunder-mifflin',
+        project: 'website',
+      },
+    );
+
+    await expect(
+      readFile(join(MEMFS_VOLUME, 'report-diff.md'), 'utf8'),
+    ).resolves.toContain(
+      `[🕵️ See full comparison in Code PushUp portal 🔍](https://code-pushup.example.com/portal/dunder-mifflin/website/comparison/${commitShas.before}/${commitShas.after})`,
+    );
+
+    expect(getPortalComparisonLink).toHaveBeenCalledWith<
+      Parameters<typeof getPortalComparisonLink>
+    >({
+      server: 'https://api.code-pushup.dev/graphql',
+      apiKey: 'cp_XXXXX',
+      parameters: {
+        organization: 'dunder-mifflin',
+        project: 'website',
+        before: commitShas.before,
+        after: commitShas.after,
+      },
+    });
+  });
+
+  it('should not include portal link in Markdown if upload config is missing', async () => {
+    await compareReportFiles(
+      {
+        before: join(MEMFS_VOLUME, 'source-report.json'),
+        after: join(MEMFS_VOLUME, 'target-report.json'),
+      },
+      { outputDir: MEMFS_VOLUME, filename: 'report', format: ['json', 'md'] },
+      undefined,
+    );
+
+    await expect(
+      readFile(join(MEMFS_VOLUME, 'report-diff.md'), 'utf8'),
+    ).resolves.not.toContain(
+      '[🕵️ See full comparison in Code PushUp portal 🔍]',
+    );
+
+    expect(getPortalComparisonLink).not.toHaveBeenCalled();
+  });
+
+  it('should not include portal link in Markdown if report has no associated commits', async () => {
+    vol.fromJSON(
+      {
+        'source-report.json': JSON.stringify({
+          ...MINIMAL_REPORT_MOCK,
+          commit: null,
+        } satisfies Report),
+        'target-report.json': JSON.stringify(REPORT_MOCK),
+      },
+      MEMFS_VOLUME,
+    );
+    await compareReportFiles(
+      {
+        before: join(MEMFS_VOLUME, 'source-report.json'),
+        after: join(MEMFS_VOLUME, 'target-report.json'),
+      },
+      { outputDir: MEMFS_VOLUME, filename: 'report', format: ['json', 'md'] },
+      {
+        server: 'https://api.code-pushup.dev/graphql',
+        apiKey: 'cp_XXXXX',
+        organization: 'dunder-mifflin',
+        project: 'website',
+      },
+    );
+
+    await expect(
+      readFile(join(MEMFS_VOLUME, 'report-diff.md'), 'utf8'),
+    ).resolves.not.toContain(
+      '[🕵️ See full comparison in Code PushUp portal 🔍]',
+    );
+
+    expect(getPortalComparisonLink).not.toHaveBeenCalled();
+  });
+
+  it('should not fetch portal link if Markdown not included in formats', async () => {
+    await compareReportFiles(
+      {
+        before: join(MEMFS_VOLUME, 'source-report.json'),
+        after: join(MEMFS_VOLUME, 'target-report.json'),
+      },
+      { outputDir: MEMFS_VOLUME, filename: 'report', format: ['json'] },
+      {
+        server: 'https://api.code-pushup.dev/graphql',
+        apiKey: 'cp_XXXXX',
+        organization: 'dunder-mifflin',
+        project: 'website',
+      },
+    );
+
+    expect(getPortalComparisonLink).not.toHaveBeenCalled();
+
+    await expect(
+      fileExists(join(MEMFS_VOLUME, 'report-diff.md')),
+    ).resolves.toBeFalsy();
+  });
 });
 
 describe('compareReports', () => {

packages/utils/src/index.ts

@@ -72,6 +72,7 @@ export {
 } from './lib/reports/flatten-plugins';
 export { generateMdReport } from './lib/reports/generate-md-report';
 export { generateMdReportsDiff } from './lib/reports/generate-md-reports-diff';
+export { loadReport } from './lib/reports/load-report';
 export { logStdoutSummary } from './lib/reports/log-stdout-summary';
 export { scoreReport } from './lib/reports/scoring';
 export { sortReport } from './lib/reports/sorting';
@@ -80,11 +81,7 @@ export {
   ScoredGroup,
   ScoredReport,
 } from './lib/reports/types';
-export {
-  calcDuration,
-  compareIssueSeverity,
-  loadReport,
-} from './lib/reports/utils';
+export { calcDuration, compareIssueSeverity } from './lib/reports/utils';
 export { isSemver, normalizeSemver, sortSemvers } from './lib/semver';
 export * from './lib/text-formats';
 export {

packages/utils/src/lib/reports/__snapshots__/report-diff-with-portal-link.md

@@ -0,0 +1,42 @@
+# Code PushUp
+
+🤨 Code PushUp report has both **improvements and regressions** – compared target commit 0123456789abcdef0123456789abcdef01234567 with source commit abcdef0123456789abcdef0123456789abcdef01.
+
+[🕵️ See full comparison in Code PushUp portal 🔍](https://app.code-pushup.dev/portal/dunder-mifflin/website/comparison/abcdef0123456789abcdef0123456789abcdef01/0123456789abcdef0123456789abcdef01234567)
+
+## 🏷️ Categories
+
+| 🏷️ Category   | ⭐ Previous score | ⭐ Current score |                         🔄 Score change                          |
+| :------------- | :--------------: | :-------------: | :--------------------------------------------------------------: |
+| Bug prevention |      🟡 68       |    🟡 **63**    | ![↓ −5](https://img.shields.io/badge/%E2%86%93%20%E2%88%925-red) |
+| Performance    |      🟢 92       |    🟢 **94**    |   ![↑ +2](https://img.shields.io/badge/%E2%86%91%20%2B2-green)   |
+| Code style     |      🟡 54       |    🟡 **54**    |                                –                                 |
+
+## 🗃️ Groups
+
+<details>
+<summary>👍 <strong>1</strong> group improved</summary>
+
+| 🔌 Plugin  | 🗃️ Group   | ⭐ Previous score | ⭐ Current score |                       🔄 Score change                        |
+| :--------- | :---------- | :--------------: | :-------------: | :----------------------------------------------------------: |
+| Lighthouse | Performance |      🟢 92       |    🟢 **94**    | ![↑ +2](https://img.shields.io/badge/%E2%86%91%20%2B2-green) |
+
+1 other group is unchanged.
+
+</details>
+
+## 🛡️ Audits
+
+<details>
+<summary>👍 <strong>3</strong> audits improved, 👎 <strong>1</strong> audit regressed</summary>
+
+| 🔌 Plugin                                                          | 🛡️ Audit                                                                                                      | 📏 Previous value | 📏 Current value |                                 🔄 Value change                                  |
+| :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | :---------------: | :--------------: | :------------------------------------------------------------------------------: |
+| [ESLint](https://www.npmjs.com/package/@code-pushup/eslint-plugin) | [Disallow unused variables](https://eslint.org/docs/latest/rules/no-unused-vars)                               |     🟩 passed     |  🟥 **1 error**  | ![↑ +∞ %](https://img.shields.io/badge/%E2%86%91%20%2B%E2%88%9E%E2%80%89%25-red) |
+| Lighthouse                                                         | [Largest Contentful Paint](https://developer.chrome.com/docs/lighthouse/performance/largest-contentful-paint/) |     🟨 1.5 s      |   🟨 **1.4 s**   | ![↓ −8 %](https://img.shields.io/badge/%E2%86%93%20%E2%88%928%E2%80%89%25-green) |
+| Lighthouse                                                         | [First Contentful Paint](https://developer.chrome.com/docs/lighthouse/performance/first-contentful-paint/)     |     🟨 1.2 s      |   🟨 **1.1 s**   | ![↓ −4 %](https://img.shields.io/badge/%E2%86%93%20%E2%88%924%E2%80%89%25-green) |
+| Lighthouse                                                         | [Speed Index](https://developer.chrome.com/docs/lighthouse/performance/speed-index/)                           |     🟩 1.2 s      |   🟩 **1.1 s**   | ![↓ −4 %](https://img.shields.io/badge/%E2%86%93%20%E2%88%924%E2%80%89%25-green) |
+
+48 other audits are unchanged.
+
+</details>