feat(ci): add searchCommits option to extend portal cache range

Author: matejchalk

packages/ci/README.md

@@ -109,6 +109,7 @@ Optionally, you can override default options for further customization:
 | `logger`           | `Logger`                  | `console`                        | Logger for reporting progress and encountered problems                                                                                                   |
 | `skipComment`      | `boolean`                 | `false`                          | Toggles if comparison comment is posted to PR                                                                                                            |
 | `configPatterns`   | `ConfigPatterns \| null`  | `null`                           | Additional configuration which enables [faster CI runs](#faster-ci-runs-with-configpatterns)                                                             |
+| `searchCommits`    | `boolean \| number`       | `false`                          | If base branch has no cached report in portal, [extends search up to 100 recent commits](#search-latest-commits-for-previous-report)                     |
 
 [^1]: By default, the `code-pushup.config` file is autodetected as described in [`@code-pushup/cli` docs](../cli/README.md#configuration).
 
@@ -217,32 +218,6 @@ await runInCI(refs, api, {
 });
 ```
 
-### Faster CI runs with `configPatterns`
-
-By default, the `print-config` command is run sequentially for each project in order to reliably detect how `code-pushup` is configured - specifically, where to read output files from (`persist` config) and whether portal may be used as a cache (`upload` config). This allows for each project to be configured in its own way without breaking anything, but for large monorepos these extra `code-pushup print-config` executions can accumulate and significantly slow down CI pipelines.
-
-As a more scalable alternative, `configPatterns` may be provided. A user declares upfront how every project is configured, which allows `print-config` to be skipped. It's the user's responsibility to ensure this configuration holds for every project (it won't be checked). The `configPatterns` support string interpolation, substituting `{projectName}` with each project's name. Other than that, each project's `code-pushup.config` must have exactly the same `persist` and `upload` configurations.
-
-```ts
-await runInCI(refs, api, {
-  monorepo: true,
-  configPatterns: {
-    persist: {
-      outputDir: '.code-pushup/{projectName}',
-      filename: 'report',
-      format: ['json', 'md'],
-    },
-    // optional: will use portal as cache when comparing reports in PRs
-    upload: {
-      server: 'https://api.code-pushup.example.com/graphql',
-      apiKey: 'cp_...',
-      organization: 'example',
-      project: '{projectName}',
-    },
-  },
-});
-```
-
 ### Monorepo result
 
 In monorepo mode, the resolved object includes the merged diff at the top-level, as well as a list of projects.
@@ -273,3 +248,48 @@ if (result.mode === 'monorepo') {
   }
 }
 ```
+
+## Advanced usage
+
+### Faster CI runs with `configPatterns`
+
+By default, the `print-config` command is run sequentially for each project in order to reliably detect how `code-pushup` is configured - specifically, where to read output files from (`persist` config) and whether portal may be used as a cache (`upload` config). This allows for each project to be configured in its own way without breaking anything, but for large monorepos these extra `code-pushup print-config` executions can accumulate and significantly slow down CI pipelines.
+
+As a more scalable alternative, `configPatterns` may be provided. A user declares upfront how every project is configured, which allows `print-config` to be skipped. It's the user's responsibility to ensure this configuration holds for every project (it won't be checked). The `configPatterns` support string interpolation, substituting `{projectName}` with each project's name. Other than that, each project's `code-pushup.config` must have exactly the same `persist` and `upload` configurations.
+
+```ts
+await runInCI(refs, api, {
+  monorepo: true,
+  configPatterns: {
+    persist: {
+      outputDir: '.code-pushup/{projectName}',
+      filename: 'report',
+      format: ['json', 'md'],
+    },
+    // optional: will use portal as cache when comparing reports in PRs
+    upload: {
+      server: 'https://api.code-pushup.example.com/graphql',
+      apiKey: 'cp_...',
+      organization: 'example',
+      project: '{projectName}',
+    },
+  },
+});
+```
+
+### Search latest commits for previous report
+
+When comparing reports, the report for the base branch can be cached. If a project has an `upload` configuration, then the Portal API is queried for a report matching that commit. If no such report was uploaded, then the report is looked up in CI artifacts (implemented in `downloadReportArtifact` in [`ProviderApiClient`](#provider-api-client)). If there's no report to be found, then the base branch is checked and the previous report is collected.
+
+In some scenarios, there may not be a report for the latest commit in main branch, but some other recent commit may have a usable report - e.g. if `nxProjectsFilter` is used with `--affected` flag. In that case, the `searchCommits` option can be enabled. Then a limited number of recent commits in the main branch will be checked, but.
+
+```ts
+await runInCI(refs, api, {
+  monorepo: 'nx',
+  nxProjectsFilter: '--with-target=code-pushup --affected',
+  // checks 10 most recent commits by default
+  searchCommits: true,
+  // optionally, number of searched commits may be extended up to 100
+  // searchCommits: 30
+});
+```

packages/ci/src/lib/constants.ts

@@ -15,4 +15,8 @@ export const DEFAULT_SETTINGS: Settings = {
   nxProjectsFilter: '--with-target={task}',
   skipComment: false,
   configPatterns: null,
+  searchCommits: false,
 };
+
+export const MIN_SEARCH_COMMITS = 1;
+export const MAX_SEARCH_COMMITS = 100;

packages/ci/src/lib/models.ts

@@ -21,6 +21,7 @@ export type Options = {
   logger?: Logger;
   skipComment?: boolean;
   configPatterns?: ConfigPatterns | null;
+  searchCommits?: boolean | number;
 };
 
 /**

packages/ci/src/lib/run-utils.ts

@@ -28,13 +28,18 @@ import {
   runCompare,
   runPrintConfig,
 } from './cli/index.js';
-import { DEFAULT_SETTINGS } from './constants.js';
+import {
+  DEFAULT_SETTINGS,
+  MAX_SEARCH_COMMITS,
+  MIN_SEARCH_COMMITS,
+} from './constants.js';
 import { listChangedFiles, normalizeGitRef } from './git.js';
 import { type SourceFileIssue, filterRelevantIssues } from './issues.js';
 import type {
   ConfigPatterns,
   GitBranch,
   GitRefs,
+  Logger,
   Options,
   OutputFiles,
   ProjectRunResult,
@@ -101,12 +106,40 @@ export async function createRunEnv(
     api,
     settings: {
       ...DEFAULT_SETTINGS,
-      ...(options && removeUndefinedAndEmptyProps(options)),
+      ...(options && sanitizeOptions(options)),
     },
     git,
   };
 }
 
+function sanitizeOptions(options: Options): Options {
+  const logger = options.logger ?? DEFAULT_SETTINGS.logger;
+
+  return removeUndefinedAndEmptyProps({
+    ...options,
+    searchCommits: sanitizeSearchCommits(options.searchCommits, logger),
+  });
+}
+
+function sanitizeSearchCommits(
+  searchCommits: Options['searchCommits'],
+  logger: Logger,
+): Options['searchCommits'] {
+  if (
+    typeof searchCommits === 'number' &&
+    (!Number.isInteger(searchCommits) ||
+      searchCommits < MIN_SEARCH_COMMITS ||
+      searchCommits > MAX_SEARCH_COMMITS)
+  ) {
+    logger.warn(
+      `The searchCommits option must be a boolean or an integer in range ${MIN_SEARCH_COMMITS} to ${MAX_SEARCH_COMMITS}, ignoring invalid value ${searchCommits}.`,
+    );
+    return undefined;
+  }
+
+  return searchCommits;
+}
+
 export async function runOnProject(
   project: ProjectConfig | null,
   env: RunEnv,
@@ -382,8 +415,13 @@ async function loadCachedBaseReportFromPortal(
     parameters: {
       organization: config.upload.organization,
       project: config.upload.project,
-      commit: base.sha,
       withAuditDetails: true,
+      ...(!settings.searchCommits && {
+        commit: base.sha,
+      }),
+      ...(typeof settings.searchCommits === 'number' && {
+        maxCommits: settings.searchCommits,
+      }),
     },
   }).catch((error: unknown) => {
     logger.warn(