@code-pushup/core 0.34.0 → 0.39.0

package/index.js

@@ -578,10 +578,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(
@@ -888,7 +892,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;
     }
@@ -1289,11 +1293,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()) {
@@ -1304,6 +1306,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) {
@@ -1617,19 +1671,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"
@@ -1645,7 +1699,7 @@ function formatDiffGroupsSection(diff) {
     return "";
   }
   return paragraphs(
-    h2("\u{1F397}\uFE0F Groups"),
+    h2("\u{1F5C3}\uFE0F Groups"),
     formatGroupsOrAuditsDetails("group", diff.groups, {
       headings: [
         "\u{1F50C} Plugin",
@@ -1655,8 +1709,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)
@@ -1677,8 +1731,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()
         )}`,
@@ -1709,7 +1763,7 @@ function formatGroupsOrAuditsDetails(token, { changed, unchanged }, table) {
 }
 function formatScoreChange(diff) {
   const marker = getDiffMarker(diff);
-  const text = formatDiffNumber(Math.round(diff * 100));
+  const text = formatDiffNumber(Math.round(diff * 1e3) / 10);
   return colorByScoreDiff(`${marker} ${text}`, diff);
 }
 function formatValueChange({
@@ -1746,6 +1800,15 @@ function summarizeDiffOutcomes(outcomes, token) {
     }
   }).join(", ");
 }
+function formatTitle({
+  title,
+  docsUrl
+}) {
+  if (docsUrl) {
+    return link(docsUrl, title);
+  }
+  return title;
+}
 function sortChanges(changes) {
   return [...changes].sort(
     (a, b) => Math.abs(b.scores.diff) - Math.abs(a.scores.diff) || Math.abs(b.values?.diff ?? 0) - Math.abs(a.values?.diff ?? 0)
@@ -2034,7 +2097,7 @@ var verboseUtils = (verbose = false) => ({
 
 // packages/core/package.json
 var name = "@code-pushup/core";
-var version = "0.34.0";
+var version = "0.39.0";
 
 // packages/core/src/lib/implementation/execute-plugin.ts
 import chalk5 from "chalk";
@@ -2317,8 +2380,7 @@ function compareAudits2(reports) {
 }
 function categoryToResult(category) {
   return {
-    slug: category.slug,
-    title: category.title,
+    ...selectMeta(category),
     score: category.score
   };
 }
@@ -2327,8 +2389,7 @@ function categoryPairToDiff({
   after
 }) {
   return {
-    slug: after.slug,
-    title: after.title,
+    ...selectMeta(after),
     scores: {
       before: before.score,
       after: after.score,
@@ -2338,12 +2399,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
   };
 }
@@ -2352,12 +2409,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,
@@ -2367,12 +2420,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
@@ -2383,12 +2432,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,
@@ -2405,6 +2450,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) {
@@ -2460,45 +2514,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 {
@@ -2579,6 +2596,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),
@@ -2627,6 +2645,98 @@ async function upload(options, 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(options, git = simpleGit2()) {
+  const { from, to } = options;
+  if (to && !from) {
+    throw new Error(
+      `git log command needs the "from" option defined to accept the "to" option.
+`
+    );
+  }
+  const logs = await git.log({
+    ...options,
+    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
+  );
+}
 export {
   ConfigPathError,
   PersistDirError,
@@ -2639,6 +2749,8 @@ export {
   compareReports,
   executePlugin,
   executePlugins,
+  getHashes,
+  history,
   persistReport,
   readRcByPath,
   upload

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@code-pushup/core",
-  "version": "0.34.0",
+  "version": "0.39.0",
   "license": "MIT",
   "dependencies": {
-    "@code-pushup/models": "0.34.0",
-    "@code-pushup/utils": "0.34.0",
+    "@code-pushup/models": "0.39.0",
+    "@code-pushup/utils": "0.39.0",
     "@code-pushup/portal-client": "^0.6.1",
     "chalk": "^5.3.0",
     "simple-git": "^3.20.0"

package/src/index.d.ts

@@ -4,6 +4,7 @@ export { CollectOptions, collect } from './lib/implementation/collect';
 export { ReportsToCompare } from './lib/implementation/compare-scorables';
 export { PluginOutputMissingAuditError, executePlugin, executePlugins, } from './lib/implementation/execute-plugin';
 export { PersistDirError, PersistError, persistReport, } from './lib/implementation/persist';
+export { history, HistoryOptions, HistoryOnlyOptions, getHashes, } from './lib/history';
 export { ConfigPathError, autoloadRc, readRcByPath, } from './lib/implementation/read-rc-file';
 export { GlobalOptions } from './lib/types';
 export { UploadOptions, upload } from './lib/upload';

package/src/lib/history.d.ts

@@ -6,10 +6,49 @@ export type HistoryOnlyOptions = {
     skipUploads?: boolean;
     forceCleanStatus?: boolean;
 };
-export type HistoryOptions = Required<Pick<CoreConfig, 'plugins' | 'categories'>> & {
+export type HistoryOptions = Required<Pick<CoreConfig, 'plugins'> & Required<Pick<CoreConfig, 'categories'>>> & {
     persist: Required<PersistConfig>;
     upload?: Required<UploadConfig>;
 } & HistoryOnlyOptions & Partial<GlobalOptions>;
 export declare function history(config: HistoryOptions, commits: string[]): Promise<string[]>;
+/**
+ * `getHashes` returns a list of commit hashes. Internally it uses `git.log()` to determine the commits within a range.
+ * The amount can be limited to a maximum number of commits specified by `maxCount`.
+ * With `from` and `to`, you can specify a range of commits.
+ *
+ * **NOTE:**
+ * In Git, specifying a range with two dots (`from..to`) selects commits that are reachable from `to` but not from `from`.
+ * Essentially, it shows the commits that are in `to` but not in `from`, excluding the commits unique to `from`.
+ *
+ * Example:
+ *
+ * Let's consider the following commit history:
+ *
+ *   A---B---C---D---E (main)
+ *
+ * Using `git log B..D`, you would get the commits C and D:
+ *
+ *   C---D
+ *
+ * This is because these commits are reachable from D but not from B.
+ *
+ * ASCII Representation:
+ *
+ *   Main Branch:    A---B---C---D---E
+ *                       \       \
+ *                        \       +--- Commits included in `git log B..D`
+ *                         \
+ *                          +--- Excluded by the `from` parameter
+ *
+ * With `simple-git`, when you specify a `from` and `to` range like this:
+ *
+ *   git.log({ from: 'B', to: 'D' });
+ *
+ * It interprets it similarly, selecting commits between B and D, inclusive of D but exclusive of B.
+ * For `git.log({ from: 'B', to: 'D' })` or `git log B..D`, commits C and D are selected.
+ *
+ * @param options Object containing `from`, `to`, and optionally `maxCount` to specify the commit range and limit.
+ * @param git The `simple-git` instance used to execute Git commands.
+ */
 export declare function getHashes(options: LogOptions, git?: import("simple-git").SimpleGit): Promise<string[]>;
 export declare function prepareHashes(logs: LogResult): string[];