@code-pushup/cli 0.35.0 → 0.39.0

package/README.md

@@ -168,9 +168,9 @@ Each example is fully tested to demonstrate best practices for plugin testing as
 
 **Example for custom plugins:**
 
-- 📏 [File Size](../../examples/plugins/src/file-size)
-- 📦 [Package Json](../../examples/plugins/src/package-json)
-- 🔥 [Lighthouse](../../examples/plugins/src/lighthouse) (official implementation [here](../../../../packages/plugin-lighthouse))
+- 📏 [File Size](../../examples/plugins/src/file-size) - example of basic runner executor
+- 📦 [Package Json](../../examples/plugins/src/package-json) - example of audits and groups
+- 🔥 [Lighthouse](../../examples/plugins/src/lighthouse) (official implementation [here](../../../../packages/plugin-lighthouse)) - example of a basic command executor
 
 ## CLI commands and options
 
@@ -240,6 +240,25 @@ Run plugins, collect results and upload the report to the Code PushUp portal.
 
 Refer to the [Common Command Options](#common-command-options) for the list of available options.
 
+#### `history` command
+
+Usage:
+`code-pushup history`
+
+Description:
+Run plugins, collect results and upload the report to the Code PushUp portal for a specified number of commits.
+
+Refer to the [Common Command Options](#common-command-options) for the list of available options.
+
+| Option                   | Type      | Default | Description                                                      |
+| ------------------------ | --------- | ------- | ---------------------------------------------------------------- |
+| **`--targetBranch`**     | `string`  | 'main'  | Branch to crawl history.                                         |
+| **`--forceCleanStatus`** | `boolean` | `false` | If we reset the status to a clean git history forcefully or not. |
+| **`--maxCount`**         | `number`  | 5       | Number of commits.                                               |
+| **`--skipUploads`**      | `boolean` | `false` | Upload created reports                                           |
+| **`--from`**             | `string`  | n/a     | Hash to start in history                                         |
+| **`--to`**               | `string`  | n/a     | Hash to end in history                                           |
+
 ### `compare` command
 
 Usage:

package/index.js

@@ -591,10 +591,14 @@ function makeArraysComparisonSchema(diffSchema, resultSchema, description) {
     { description }
   );
 }
-var scorableMetaSchema = z14.object({ slug: slugSchema, title: titleSchema });
+var scorableMetaSchema = z14.object({
+  slug: slugSchema,
+  title: titleSchema,
+  docsUrl: docsUrlSchema
+});
 var scorableWithPluginMetaSchema = scorableMetaSchema.merge(
   z14.object({
-    plugin: pluginMetaSchema.pick({ slug: true, title: true }).describe("Plugin which defines it")
+    plugin: pluginMetaSchema.pick({ slug: true, title: true, docsUrl: true }).describe("Plugin which defines it")
   })
 );
 var scorableDiffSchema = scorableMetaSchema.merge(
@@ -904,7 +908,7 @@ async function ensureDirectoryExists(baseDir) {
     await mkdir(baseDir, { recursive: true });
     return;
   } catch (error) {
-    ui().logger.error(error.message);
+    ui().logger.info(error.message);
     if (error.code !== "EEXIST") {
       throw error;
     }
@@ -1316,11 +1320,9 @@ function toUnixPath(path) {
 async function getLatestCommit(git = simpleGit()) {
   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" }
   });
-  if (!log2.latest) {
-    return null;
-  }
   return commitSchema.parse(log2.latest);
 }
 function getGitRoot(git = simpleGit()) {
@@ -1331,6 +1333,58 @@ function formatGitPath(path, gitRoot) {
   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 getCurrentBranchOrTag(git = simpleGit()) {
+  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());
+}
+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/group-by-status.ts
 function groupByStatus(results) {
@@ -1644,19 +1698,19 @@ function formatDiffCategoriesSection(diff) {
           "\u{1F504} Score change"
         ],
         ...sortChanges(changed).map((category) => [
-          category.title,
+          formatTitle(category),
           formatScoreWithColor(category.scores.after),
           formatScoreWithColor(category.scores.before, { skipBold: true }),
           formatScoreChange(category.scores.diff)
         ]),
         ...added.map((category) => [
-          category.title,
+          formatTitle(category),
           formatScoreWithColor(category.score),
           style("n/a (\\*)", ["i"]),
           style("n/a (\\*)", ["i"])
         ]),
         ...unchanged.map((category) => [
-          category.title,
+          formatTitle(category),
           formatScoreWithColor(category.score),
           formatScoreWithColor(category.score, { skipBold: true }),
           "\u2013"
@@ -1682,8 +1736,8 @@ function formatDiffGroupsSection(diff) {
         "\u{1F504} Score change"
       ],
       rows: sortChanges(diff.groups.changed).map((group) => [
-        group.plugin.title,
-        group.title,
+        formatTitle(group.plugin),
+        formatTitle(group),
         formatScoreWithColor(group.scores.after),
         formatScoreWithColor(group.scores.before, { skipBold: true }),
         formatScoreChange(group.scores.diff)
@@ -1704,8 +1758,8 @@ function formatDiffAuditsSection(diff) {
         "\u{1F504} Value change"
       ],
       rows: sortChanges(diff.audits.changed).map((audit) => [
-        audit.plugin.title,
-        audit.title,
+        formatTitle(audit.plugin),
+        formatTitle(audit),
         `${getSquaredScoreMarker(audit.scores.after)} ${style(
           audit.displayValues.after || audit.values.after.toString()
         )}`,
@@ -1773,6 +1827,15 @@ function summarizeDiffOutcomes(outcomes, token) {
     }
   }).join(", ");
 }
+function formatTitle({
+  title,
+  docsUrl
+}) {
+  if (docsUrl) {
+    return link2(docsUrl, title);
+  }
+  return title;
+}
 function sortChanges(changes) {
   return [...changes].sort(
     (a, b) => Math.abs(b.scores.diff) - Math.abs(a.scores.diff) || Math.abs(b.values?.diff ?? 0) - Math.abs(a.values?.diff ?? 0)
@@ -2061,7 +2124,7 @@ var verboseUtils = (verbose = false) => ({
 
 // packages/core/package.json
 var name = "@code-pushup/core";
-var version = "0.35.0";
+var version = "0.39.0";
 
 // packages/core/src/lib/implementation/execute-plugin.ts
 import chalk5 from "chalk";
@@ -2344,8 +2407,7 @@ function compareAudits2(reports) {
 }
 function categoryToResult(category) {
   return {
-    slug: category.slug,
-    title: category.title,
+    ...selectMeta(category),
     score: category.score
   };
 }
@@ -2354,8 +2416,7 @@ function categoryPairToDiff({
   after
 }) {
   return {
-    slug: after.slug,
-    title: after.title,
+    ...selectMeta(after),
     scores: {
       before: before.score,
       after: after.score,
@@ -2365,12 +2426,8 @@ function categoryPairToDiff({
 }
 function pluginGroupToResult({ group, plugin }) {
   return {
-    slug: group.slug,
-    title: group.title,
-    plugin: {
-      slug: plugin.slug,
-      title: plugin.title
-    },
+    ...selectMeta(group),
+    plugin: selectMeta(plugin),
     score: group.score
   };
 }
@@ -2379,12 +2436,8 @@ function pluginGroupPairToDiff({
   after
 }) {
   return {
-    slug: after.group.slug,
-    title: after.group.title,
-    plugin: {
-      slug: after.plugin.slug,
-      title: after.plugin.title
-    },
+    ...selectMeta(after.group),
+    plugin: selectMeta(after.plugin),
     scores: {
       before: before.group.score,
       after: after.group.score,
@@ -2394,12 +2447,8 @@ function pluginGroupPairToDiff({
 }
 function pluginAuditToResult({ audit, plugin }) {
   return {
-    slug: audit.slug,
-    title: audit.title,
-    plugin: {
-      slug: plugin.slug,
-      title: plugin.title
-    },
+    ...selectMeta(audit),
+    plugin: selectMeta(plugin),
     score: audit.score,
     value: audit.value,
     displayValue: audit.displayValue
@@ -2410,12 +2459,8 @@ function pluginAuditPairToDiff({
   after
 }) {
   return {
-    slug: after.audit.slug,
-    title: after.audit.title,
-    plugin: {
-      slug: after.plugin.slug,
-      title: after.plugin.title
-    },
+    ...selectMeta(after.audit),
+    plugin: selectMeta(after.plugin),
     scores: {
       before: before.audit.score,
       after: after.audit.score,
@@ -2432,6 +2477,15 @@ function pluginAuditPairToDiff({
     }
   };
 }
+function selectMeta(meta) {
+  return {
+    slug: meta.slug,
+    title: meta.title,
+    ...meta.docsUrl && {
+      docsUrl: meta.docsUrl
+    }
+  };
+}
 
 // packages/core/src/lib/compare.ts
 async function compareReportFiles(inputPaths, persistConfig) {
@@ -2487,45 +2541,8 @@ function reportsDiffToFileContent(reportsDiff, format) {
   }
 }
 
-// packages/core/src/lib/implementation/read-rc-file.ts
-import { join as join6 } from "node:path";
-var ConfigPathError = class extends Error {
-  constructor(configPath) {
-    super(`Provided path '${configPath}' is not valid.`);
-  }
-};
-async function readRcByPath(filepath, tsconfig) {
-  if (filepath.length === 0) {
-    throw new Error("The path to the configuration file is empty.");
-  }
-  if (!await fileExists(filepath)) {
-    throw new ConfigPathError(filepath);
-  }
-  const cfg = await importEsmModule({ filepath, tsconfig });
-  return coreConfigSchema.parse(cfg);
-}
-async function autoloadRc(tsconfig) {
-  let ext = "";
-  for (const extension of SUPPORTED_CONFIG_FILE_FORMATS) {
-    const path = `${CONFIG_FILE_NAME}.${extension}`;
-    const exists2 = await fileExists(path);
-    if (exists2) {
-      ext = extension;
-      break;
-    }
-  }
-  if (!ext) {
-    throw new Error(
-      `No file ${CONFIG_FILE_NAME}.(${SUPPORTED_CONFIG_FILE_FORMATS.join(
-        "|"
-      )}) present in ${process.cwd()}`
-    );
-  }
-  return readRcByPath(
-    join6(process.cwd(), `${CONFIG_FILE_NAME}.${ext}`),
-    tsconfig
-  );
-}
+// packages/core/src/lib/history.ts
+import { simpleGit as simpleGit2 } from "simple-git";
 
 // packages/core/src/lib/upload.ts
 import {
@@ -2606,6 +2623,7 @@ function categoryToGQL(category) {
     slug: category.slug,
     title: category.title,
     description: category.description,
+    isBinary: category.isBinary,
     refs: category.refs.map((ref) => ({
       plugin: ref.plugin,
       type: categoryRefTypeToGQL(ref.type),
@@ -2655,6 +2673,98 @@ async function upload(options2, uploadFn = uploadToPortal) {
   return uploadFn({ apiKey, server, data, timeout });
 }
 
+// packages/core/src/lib/history.ts
+async function history(config, commits) {
+  const initialBranch = await getCurrentBranchOrTag();
+  const { skipUploads = false, forceCleanStatus, persist } = config;
+  const reports = [];
+  for (const commit of commits) {
+    ui().logger.info(`Collect ${commit}`);
+    await safeCheckout(commit, forceCleanStatus);
+    const currentConfig = {
+      ...config,
+      persist: {
+        ...persist,
+        format: ["json"],
+        filename: `${commit}-report`
+      }
+    };
+    await collectAndPersistReports(currentConfig);
+    if (skipUploads) {
+      ui().logger.info("Upload is skipped because skipUploads is set to true.");
+    } else {
+      if (currentConfig.upload) {
+        await upload(currentConfig);
+      } else {
+        ui().logger.info(
+          "Upload is skipped because upload config is undefined."
+        );
+      }
+    }
+    reports.push(currentConfig.persist.filename);
+  }
+  await safeCheckout(initialBranch, forceCleanStatus);
+  return reports;
+}
+async function getHashes(options2, git = simpleGit2()) {
+  const { from, to } = options2;
+  if (to && !from) {
+    throw new Error(
+      `git log command needs the "from" option defined to accept the "to" option.
+`
+    );
+  }
+  const logs = await git.log({
+    ...options2,
+    from,
+    to
+  });
+  return prepareHashes(logs);
+}
+function prepareHashes(logs) {
+  return logs.all.map(({ hash }) => hash).reverse();
+}
+
+// packages/core/src/lib/implementation/read-rc-file.ts
+import { join as join6 } from "node:path";
+var ConfigPathError = class extends Error {
+  constructor(configPath) {
+    super(`Provided path '${configPath}' is not valid.`);
+  }
+};
+async function readRcByPath(filepath, tsconfig) {
+  if (filepath.length === 0) {
+    throw new Error("The path to the configuration file is empty.");
+  }
+  if (!await fileExists(filepath)) {
+    throw new ConfigPathError(filepath);
+  }
+  const cfg = await importEsmModule({ filepath, tsconfig });
+  return coreConfigSchema.parse(cfg);
+}
+async function autoloadRc(tsconfig) {
+  let ext = "";
+  for (const extension of SUPPORTED_CONFIG_FILE_FORMATS) {
+    const path = `${CONFIG_FILE_NAME}.${extension}`;
+    const exists2 = await fileExists(path);
+    if (exists2) {
+      ext = extension;
+      break;
+    }
+  }
+  if (!ext) {
+    throw new Error(
+      `No file ${CONFIG_FILE_NAME}.(${SUPPORTED_CONFIG_FILE_FORMATS.join(
+        "|"
+      )}) present in ${process.cwd()}`
+    );
+  }
+  return readRcByPath(
+    join6(process.cwd(), `${CONFIG_FILE_NAME}.${ext}`),
+    tsconfig
+  );
+}
+
 // packages/cli/src/lib/constants.ts
 var CLI_NAME = "Code PushUp CLI";
 var CLI_SCRIPT_NAME = "code-pushup";
@@ -2814,6 +2924,9 @@ function yargsCompareCommandObject() {
   };
 }
 
+// packages/cli/src/lib/history/history-command.ts
+import chalk10 from "chalk";
+
 // packages/cli/src/lib/implementation/global.utils.ts
 function filterKebabCaseKeys(obj) {
   return Object.entries(obj).filter(([key]) => !key.includes("-")).reduce(
@@ -2839,6 +2952,104 @@ function coerceArray(param) {
   return [...new Set(toArray(param).flatMap((f) => f.split(",")))];
 }
 
+// packages/cli/src/lib/implementation/only-plugins.options.ts
+var onlyPluginsOption = {
+  describe: "List of plugins to run. If not set all plugins are run.",
+  type: "array",
+  default: [],
+  coerce: coerceArray
+};
+function yargsOnlyPluginsOptionsDefinition() {
+  return {
+    onlyPlugins: onlyPluginsOption
+  };
+}
+
+// packages/cli/src/lib/history/history.options.ts
+function yargsHistoryOptionsDefinition() {
+  return {
+    targetBranch: {
+      describe: "Branch to crawl history",
+      type: "string",
+      default: "main"
+    },
+    forceCleanStatus: {
+      describe: "If we reset the status to a clean git history forcefully or not.",
+      type: "boolean",
+      default: false
+    },
+    skipUploads: {
+      describe: "Upload created reports",
+      type: "boolean",
+      default: false
+    },
+    maxCount: {
+      // https://git-scm.com/docs/git-log#Documentation/git-log.txt---max-countltnumbergt
+      describe: "Number of steps in history",
+      type: "number",
+      // eslint-disable-next-line no-magic-numbers
+      default: 5
+    },
+    from: {
+      // https://git-scm.com/docs/git-log#Documentation/git-log.txt-ltrevision-rangegt
+      describe: "hash to first commit in history",
+      type: "string"
+    },
+    to: {
+      // https://git-scm.com/docs/git-log#Documentation/git-log.txt-ltrevision-rangegt
+      describe: "hash to last commit in history",
+      type: "string"
+    }
+  };
+}
+
+// packages/cli/src/lib/history/history-command.ts
+function yargsHistoryCommandObject() {
+  const command = "history";
+  return {
+    command,
+    describe: "Collect reports for commit history",
+    builder: (yargs2) => {
+      yargs2.options({
+        ...yargsHistoryOptionsDefinition(),
+        ...yargsOnlyPluginsOptionsDefinition()
+      });
+      yargs2.group(
+        Object.keys(yargsHistoryOptionsDefinition()),
+        "History Options:"
+      );
+      return yargs2;
+    },
+    handler: async (args) => {
+      ui().logger.info(chalk10.bold(CLI_NAME));
+      ui().logger.info(chalk10.gray(`Run ${command}`));
+      const currentBranch = await getCurrentBranchOrTag();
+      const {
+        targetBranch = currentBranch,
+        forceCleanStatus,
+        maxCount,
+        from,
+        to,
+        ...restOptions
+      } = args;
+      const commits = await getHashes({ maxCount, from, to });
+      try {
+        const reports = await history(
+          {
+            ...restOptions,
+            targetBranch,
+            forceCleanStatus
+          },
+          commits
+        );
+        ui().logger.log(`Reports: ${reports.length}`);
+      } finally {
+        await safeCheckout(currentBranch);
+      }
+    }
+  };
+}
+
 // packages/cli/src/lib/print-config/print-config-command.ts
 function yargsConfigCommandObject() {
   const command = "print-config";
@@ -2854,15 +3065,15 @@ function yargsConfigCommandObject() {
 }
 
 // packages/cli/src/lib/upload/upload-command.ts
-import chalk10 from "chalk";
+import chalk11 from "chalk";
 function yargsUploadCommandObject() {
   const command = "upload";
   return {
     command,
     describe: "Upload report results to the portal",
     handler: async (args) => {
-      ui().logger.log(chalk10.bold(CLI_NAME));
-      ui().logger.info(chalk10.gray(`Run ${command}...`));
+      ui().logger.log(chalk11.bold(CLI_NAME));
+      ui().logger.info(chalk11.gray(`Run ${command}...`));
       const options2 = args;
       if (options2.upload == null) {
         renderIntegratePortalHint();
@@ -2883,6 +3094,7 @@ var commands = [
   yargsAutorunCommandObject(),
   yargsCollectCommandObject(),
   yargsUploadCommandObject(),
+  yargsHistoryCommandObject(),
   yargsCompareCommandObject(),
   yargsConfigCommandObject()
 ];
@@ -2922,7 +3134,7 @@ async function coreConfigMiddleware(processArgs) {
 }
 
 // packages/cli/src/lib/implementation/only-plugins.utils.ts
-import chalk11 from "chalk";
+import chalk12 from "chalk";
 function validateOnlyPluginsOption({
   plugins,
   categories
@@ -2936,7 +3148,7 @@ function validateOnlyPluginsOption({
   );
   if (missingPlugins.length > 0 && verbose) {
     ui().logger.info(
-      `${chalk11.yellow(
+      `${chalk12.yellow(
         "\u26A0"
       )} The --onlyPlugin argument references plugins with "${missingPlugins.join(
         '", "'
@@ -3063,19 +3275,6 @@ function yargsGlobalOptionsDefinition() {
   };
 }
 
-// packages/cli/src/lib/implementation/only-plugins.options.ts
-var onlyPluginsOption = {
-  describe: "List of plugins to run. If not set all plugins are run.",
-  type: "array",
-  default: [],
-  coerce: coerceArray
-};
-function yargsOnlyPluginsOptionsDefinition() {
-  return {
-    onlyPlugins: onlyPluginsOption
-  };
-}
-
 // packages/cli/src/lib/options.ts
 var options = {
   ...yargsGlobalOptionsDefinition(),
@@ -3092,7 +3291,7 @@ var groups = {
 };
 
 // packages/cli/src/lib/yargs-cli.ts
-import chalk12 from "chalk";
+import chalk13 from "chalk";
 import yargs from "yargs";
 function yargsCli(argv, cfg) {
   const { usageMessage, scriptName, noExitProcess } = cfg;
@@ -3112,7 +3311,7 @@ function yargsCli(argv, cfg) {
     (config) => Array.isArray(config) ? config.at(-1) : config
   ).options(options2).wrap(TERMINAL_WIDTH);
   if (usageMessage) {
-    cli2.usage(chalk12.bold(usageMessage));
+    cli2.usage(chalk13.bold(usageMessage));
   }
   if (scriptName) {
     cli2.scriptName(scriptName);

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@code-pushup/cli",
-  "version": "0.35.0",
+  "version": "0.39.0",
   "license": "MIT",
   "bin": {
     "code-pushup": "index.js"
   },
   "dependencies": {
-    "@code-pushup/models": "0.35.0",
-    "@code-pushup/core": "0.35.0",
+    "@code-pushup/models": "0.39.0",
+    "@code-pushup/core": "0.39.0",
+    "@code-pushup/utils": "0.39.0",
     "yargs": "^17.7.2",
     "chalk": "^5.3.0",
-    "@code-pushup/utils": "0.35.0"
+    "simple-git": "^3.20.0"
   },
   "homepage": "https://github.com/code-pushup/cli#readme",
   "bugs": {

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

@@ -0,0 +1,7 @@
+import { ArgumentsCamelCase } from 'yargs';
+export declare function yargsHistoryCommandObject(): {
+    command: string;
+    describe: string;
+    builder: (yargs: import("yargs").Argv<{}>) => import("yargs").Argv<{}>;
+    handler: <T>(args: ArgumentsCamelCase<T>) => Promise<void>;
+};

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

@@ -0,0 +1,5 @@
+import { type LogOptions } from 'simple-git';
+import { HistoryOnlyOptions } from '@code-pushup/core';
+export type HistoryCliOptions = {
+    targetBranch?: string;
+} & Pick<LogOptions, 'maxCount' | 'from' | 'to'> & HistoryOnlyOptions;

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

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