[cli] Collect diagnostics from builders during vc build (#11653)

Adds the ability for builders to define a `diagnostics` step that is called after the build operation is done (either failed or successful).
Implements the diagnostics step in the next builder.

**References**
- vercel/next.js#66187

.changeset/hot-rules-tickle.md

@@ -0,0 +1,8 @@
+---
+'@vercel/build-utils': minor
+'@vercel/next': minor
+'vercel': minor
+---
+
+Adds the ability for builders to define a `diagnostics` step that is called after the build operation is done.
+Implements the diagnostics step in the `next` builder.

packages/build-utils/src/types.ts

@@ -362,13 +362,15 @@ export interface ProjectSettings {
 export interface BuilderV2 {
   version: 2;
   build: BuildV2;
+  diagnostics?: Diagnostics;
   prepareCache?: PrepareCache;
   shouldServe?: ShouldServe;
 }
 
 export interface BuilderV3 {
   version: 3;
   build: BuildV3;
+  diagnostics?: Diagnostics;
   prepareCache?: PrepareCache;
   shouldServe?: ShouldServe;
   startDevServer?: StartDevServer;
@@ -477,6 +479,7 @@ export interface BuildResultV3 {
 export type BuildV2 = (options: BuildOptions) => Promise<BuildResultV2>;
 export type BuildV3 = (options: BuildOptions) => Promise<BuildResultV3>;
 export type PrepareCache = (options: PrepareCacheOptions) => Promise<Files>;
+export type Diagnostics = (options: BuildOptions) => Promise<Files>;
 export type ShouldServe = (
   options: ShouldServeOptions
 ) => boolean | Promise<boolean>;

packages/cli/src/commands/build/index.ts

@@ -7,22 +7,22 @@ import { join, normalize, relative, resolve, sep } from 'path';
 import { frameworkList } from '@vercel/frameworks';
 import {
   getDiscontinuedNodeVersions,
+  getInstalledPackageVersion,
   normalizePath,
-  Files,
   FileFsRef,
-  PackageJson,
-  BuildOptions,
-  Config,
-  Meta,
-  Builder,
-  BuildResultV2,
-  BuildResultV2Typical,
-  BuildResultV3,
   NowBuildError,
-  Cron,
   validateNpmrc,
+  type Files,
+  type PackageJson,
+  type BuildOptions,
+  type Config,
+  type Meta,
+  type Builder,
+  type BuildResultV2,
+  type BuildResultV2Typical,
+  type BuildResultV3,
+  type Cron,
   type FlagDefinitions,
-  getInstalledPackageVersion,
 } from '@vercel/build-utils';
 import {
   detectBuilders,
@@ -34,15 +34,15 @@ import {
   appendRoutesToPhase,
   getTransformedRoutes,
   mergeRoutes,
-  MergeRoutesProps,
-  Route,
+  type MergeRoutesProps,
+  type Route,
 } from '@vercel/routing-utils';
 import { fileNameSymbol } from '@vercel/client';
 import type { VercelConfig } from '@vercel/client';
 
 import pull from '../pull';
 import { staticFiles as getFiles } from '../../util/get-files';
-import Client from '../../util/client';
+import type Client from '../../util/client';
 import { parseArguments } from '../../util/get-args';
 import cmd from '../../util/output/cmd';
 import * as cli from '../../util/pkg-name';
@@ -51,17 +51,17 @@ import readJSONFile from '../../util/read-json-file';
 import { CantParseJSONFile } from '../../util/errors-ts';
 import {
   pickOverrides,
-  ProjectLinkAndSettings,
   readProjectSettings,
+  type ProjectLinkAndSettings,
 } from '../../util/projects/project-settings';
 import { getProjectLink, VERCEL_DIR } from '../../util/projects/link';
 import confirm from '../../util/input/confirm';
 import { emoji, prependEmoji } from '../../util/emoji';
 import stamp from '../../util/output/stamp';
 import {
   OUTPUT_DIR,
-  PathOverride,
   writeBuildResult,
+  type PathOverride,
 } from '../../util/build/write-build-result';
 import { importBuilders } from '../../util/build/import-builders';
 import { initCorepack, cleanupCorepack } from '../../util/build/corepack';
@@ -476,6 +476,7 @@ async function doBuild(
   const overrides: PathOverride[] = [];
   const repoRootPath = cwd;
   const corepackShimDir = await initCorepack({ repoRootPath }, output);
+  const diagnostics: Files = {};
 
   for (const build of sortedBuilders) {
     if (typeof build.src !== 'string') continue;
@@ -527,7 +528,18 @@ async function doBuild(
       output.debug(
         `Building entrypoint "${build.src}" with "${builderPkg.name}"`
       );
-      const buildResult = await builder.build(buildOptions);
+      let buildResult: BuildResultV2 | BuildResultV3 | undefined;
+      try {
+        buildResult = await builder.build(buildOptions);
+      } finally {
+        // Make sure we don't fail the build
+        try {
+          Object.assign(diagnostics, await builder.diagnostics?.(buildOptions));
+        } catch (error) {
+          output.error('Collecting diagnostics failed');
+          output.debug(error);
+        }
+      }
 
       if (
         buildResult &&

packages/next/src/index.ts

@@ -1,4 +1,5 @@
 import {
+  Diagnostics,
   FileBlob,
   FileFsRef,
   Files,
@@ -2725,6 +2726,36 @@ export const build: BuildV2 = async ({
   };
 };
 
+export const diagnostics: Diagnostics = async ({
+  config,
+  entrypoint,
+  workPath,
+  repoRootPath,
+}) => {
+  const entryDirectory = path.dirname(entrypoint);
+  const entryPath = path.join(workPath, entryDirectory);
+  const outputDirectory = path.join('./', config.outputDirectory || '.next');
+  const basePath = repoRootPath || workPath;
+  const diagnosticsEntrypoint = path.relative(basePath, entryPath);
+
+  debug(
+    `Reading diagnostics file in diagnosticsEntrypoint=${diagnosticsEntrypoint}`
+  );
+
+  return {
+    // Collect output in `.next/diagnostics`
+    ...(await glob(
+      'diagnostics/*',
+      path.join(basePath, diagnosticsEntrypoint, outputDirectory, 'diagnostics')
+    )),
+    // Collect `.next/trace` file
+    ...(await glob(
+      'trace',
+      path.join(basePath, diagnosticsEntrypoint, outputDirectory)
+    )),
+  };
+};
+
 export const prepareCache: PrepareCache = async ({
   workPath,
   repoRootPath,