Unverified Commit fa0ef04c authored by vercel-fleet-prod[bot]'s avatar vercel-fleet-prod[bot] Committed by GitHub

Add bundle analyzer CLI overview

Co-authored-by: 's avatarWill Binns-Smith <755844+wbinnssmith@users.noreply.github.com>
parent e4579de5
......@@ -29,6 +29,7 @@ import type { NextStartOptions } from '../cli/next-start.js'
import type { NextInfoOptions } from '../cli/next-info.js'
import type { NextDevOptions } from '../cli/next-dev.js'
import type { NextAnalyzeOptions } from '../cli/next-analyze.js'
import type { NextAnalyzeQueryOptions } from '../cli/next-analyze-query.js'
import type { NextBuildOptions } from '../cli/next-build.js'
import type { NextTypegenOptions } from '../cli/next-typegen.js'
import type { NextPostBuildOptions } from '../cli/next-post-build.js'
......@@ -279,7 +280,7 @@ program
})
.usage('[directory] [options]')
program
const experimentalAnalyzeCommand = program
.command('experimental-analyze')
.description(
'Analyze production bundle output with an interactive web ui. Does not produce an application build. Only compatible with Turbopack.'
......@@ -323,6 +324,29 @@ program
})
})
experimentalAnalyzeCommand
.command('query')
.description('Query previously generated analyzer data as JSON.')
.argument('<name>', 'Name of the analyzer query to run.')
.argument(
'[directory]',
`The analyzed application directory. ${italic(
'If no directory is provided, the current directory will be used.'
)}`
)
.option('--input <json>', 'Query arguments as a JSON object.', '{}')
.action(
(
name: string,
directory: string | undefined,
options: NextAnalyzeQueryOptions
) => {
return import('../cli/next-analyze-query.js').then((mod) =>
mod.nextAnalyzeQuery(name, directory, options)
)
}
)
program
.command('dev', { isDefault: true })
.description(
......
import type { AnalyzeData } from '../../shared/lib/analyze-data'
import type { SnapshotMetadata } from './snapshot'
import type { AnalyzeRepository } from './repository'
import z from 'next/dist/compiled/zod'
const DEFAULT_LIMIT = 50
const MAX_LIMIT = 100
const COMPRESSED_CAVEAT =
'Compressed source sizes are estimates because attributed parts are compressed independently.'
type Environment = 'total' | 'client'
type Metric = 'raw' | 'compressed'
interface OverviewArgs {
snapshot?: string
environment?: 'total' | 'client'
metric?: Metric
routeFilter?: string
offset?: number
limit?: number
}
export class AnalyzeQueryError extends Error {
constructor(readonly output: Record<string, unknown>) {
super(
typeof output.error === 'string' ? output.error : 'Analyzer query failed'
)
}
}
function publicError(error: unknown): Record<string, unknown> {
if (!(error instanceof Error))
return { error: 'Unable to query analyzer data' }
if (error.message.startsWith('Unknown snapshot')) {
return { error: 'Unknown snapshot' }
}
if (error.message.startsWith('Unknown route'))
return { error: 'Unknown route' }
if (/^Invalid /.test(error.message)) return { error: error.message }
return { error: 'Unable to query analyzer data' }
}
function safeQuery<T, R>(fn: (args: T) => Promise<R>) {
return async (args: T) => {
try {
return await fn(args)
} catch (error) {
throw new AnalyzeQueryError(publicError(error))
}
}
}
type StoredQuery = {
name: string
execute: (input: unknown) => Promise<unknown>
}
export class AnalyzeQueryRegistry {
constructor(private readonly queries: StoredQuery[]) {}
async execute(name: string, input: unknown): Promise<unknown> {
const query = this.queries.find((item) => item.name === name)
if (!query) {
throw new AnalyzeQueryError({ error: `Unknown analyzer query: ${name}` })
}
try {
return await query.execute(input)
} catch (error) {
if (error instanceof AnalyzeQueryError) throw error
if (error instanceof z.ZodError) {
throw new AnalyzeQueryError({
error: `Invalid arguments for query ${name}: ${error.message}`,
})
}
throw error
}
}
}
function page<T>(values: T[], offset: number, limit: number) {
const result = values.slice(offset, offset + limit)
return {
values: result,
pagination: {
offset,
limit,
total: values.length,
returned: result.length,
truncated: offset + limit < values.length,
},
}
}
function compareText(a: string, b: string): number {
return a < b ? -1 : a > b ? 1 : 0
}
function metricValue(
value: { rawSize: number; compressedSize: number },
metric: Metric
): number {
return metric === 'compressed' ? value.compressedSize : value.rawSize
}
function sourceSizes(
data: AnalyzeData,
sourceIndex: number,
environment: Environment
): { rawSize: number; compressedSize: number } {
let rawSize = 0
let compressedSize = 0
for (const partIndex of data.sourceChunkParts(sourceIndex)) {
const part = data.chunkPart(partIndex)
const output = part && data.outputFile(part.output_file_index)
if (!part || !output) continue
if (
environment !== 'total' &&
(output.filename.startsWith('[client-fs]/') ? 'client' : 'server') !==
environment
) {
continue
}
rawSize += part.size
compressedSize += part.compressed_size
}
return { rawSize, compressedSize }
}
function routeSizes(data: AnalyzeData, environment: Environment) {
let rawSize = 0
let compressedSize = 0
for (let index = 0; index < data.sourceCount(); index++) {
const sizes = sourceSizes(data, index, environment)
rawSize += sizes.rawSize
compressedSize += sizes.compressedSize
}
return { rawSize, compressedSize }
}
function provenance(metadata: SnapshotMetadata) {
return {
id: metadata.id,
createdAt: metadata.createdAt,
baselineName: metadata.baselineName,
nextVersion: metadata.nextVersion,
gitBranch: metadata.gitBranch,
gitSha: metadata.gitSha,
gitDirty: metadata.gitDirty,
routeCount: metadata.routeCount,
}
}
const pagingSchema = {
offset: z.number().int().nonnegative().optional(),
limit: z.number().int().min(1).max(MAX_LIMIT).optional(),
}
const snapshotSchema = z.string().max(100).optional()
const metricSchema = z.enum(['raw', 'compressed']).optional()
export function createAnalyzeQueryRegistry(repository: AnalyzeRepository) {
const queries: StoredQuery[] = []
function registerQuery<T extends z.ZodRawShape>(
name: string,
inputSchema: T,
callback: (args: z.infer<z.ZodObject<T>>) => Promise<unknown>
) {
const schema = z.object(inputSchema).strict()
queries.push({ name, execute: (input) => callback(schema.parse(input)) })
}
registerQuery(
'get_app_overview',
{
snapshot: snapshotSchema,
environment: z.enum(['total', 'client']).optional(),
metric: metricSchema,
routeFilter: z.string().max(1000).optional(),
...pagingSchema,
},
safeQuery(async (args: OverviewArgs) => {
const snapshot = await repository.getSnapshot(args.snapshot)
const snapshots = await repository.listSnapshots()
const environment = args.environment ?? 'total'
const metric = args.metric ?? 'raw'
const filter = args.routeFilter?.toLocaleLowerCase()
const rows = []
for (const route of snapshot.routes) {
if (filter && !route.toLocaleLowerCase().includes(filter)) continue
const sizes = routeSizes(
await repository.loadRoute(args.snapshot, route),
environment
)
rows.push({ route, ...sizes })
}
rows.sort(
(a, b) =>
metricValue(b, metric) - metricValue(a, metric) ||
compareText(a.route, b.route)
)
const paged = page(rows, args.offset ?? 0, args.limit ?? DEFAULT_LIMIT)
return {
snapshot: provenance(snapshot.metadata),
snapshots: {
current: provenance(snapshots.current),
history: snapshots.history.map(provenance),
},
environment,
metric,
resultCounts: {
routesInSnapshot: snapshot.routes.length,
matched: rows.length,
},
routes: paged.values,
pagination: paged.pagination,
caveats: [COMPRESSED_CAVEAT],
}
})
)
return new AnalyzeQueryRegistry(queries)
}
import { AnalyzeRepository } from './repository'
import { AnalyzeQueryError, createAnalyzeQueryRegistry } from './queries'
export { AnalyzeQueryError }
export function queryAnalyzeData(
analyzeDir: string,
name: string,
input: Record<string, unknown>
): Promise<unknown> {
return createAnalyzeQueryRegistry(new AnalyzeRepository(analyzeDir)).execute(
name,
input
)
}
import * as path from 'node:path'
import { readFile } from 'node:fs/promises'
import { AnalyzeData, ModulesData } from '../../shared/lib/analyze-data'
import type { SnapshotMetadata } from './snapshot'
const SNAPSHOT_ID = /^\d{8}-\d{6}-(?:[0-9a-f]{7}|local)$/
const MAX_ROUTE_DATASETS = 8
const MAX_MODULE_DATASETS = 4
const MAX_INDEX_BYTES = 1024 * 1024
const MAX_HISTORY_ENTRIES = 100
interface HistoryIndex {
snapshots: SnapshotMetadata[]
}
export interface SnapshotDataset {
key: string
metadata: SnapshotMetadata
routes: string[]
directory: string
}
function toArrayBuffer(buffer: Buffer): ArrayBuffer {
return buffer.buffer.slice(
buffer.byteOffset,
buffer.byteOffset + buffer.byteLength
) as ArrayBuffer
}
function validateStringArray(value: unknown, label: string): string[] {
if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
throw new Error(`Invalid ${label}`)
}
return value
}
function validateMetadata(value: unknown, label: string): SnapshotMetadata {
const metadata = value as SnapshotMetadata
if (
typeof value !== 'object' ||
value === null ||
typeof metadata.id !== 'string' ||
!SNAPSHOT_ID.test(metadata.id) ||
typeof metadata.createdAt !== 'string' ||
!Number.isFinite(Date.parse(metadata.createdAt)) ||
!Number.isSafeInteger(metadata.routeCount) ||
metadata.routeCount < 0
) {
throw new Error(`Invalid ${label}`)
}
return metadata
}
async function readJson(filename: string, label: string): Promise<unknown> {
const contents = await readFile(filename)
if (contents.byteLength > MAX_INDEX_BYTES) throw new Error(`Invalid ${label}`)
try {
return JSON.parse(contents.toString('utf8'))
} catch {
throw new Error(`Invalid ${label}`)
}
}
function assertInside(base: string, candidate: string): void {
const relative = path.relative(base, candidate)
if (relative.startsWith('..') || path.isAbsolute(relative)) {
throw new Error('Requested analyzer data path is outside its snapshot')
}
}
function validateRoute(route: string): void {
if (
!route.startsWith('/') ||
route.includes('\\') ||
route.includes('\0') ||
route.split('/').some((segment) => segment === '.' || segment === '..')
) {
throw new Error('Invalid route')
}
try {
const decoded = decodeURIComponent(route)
if (
decoded.includes('\\') ||
decoded.includes('\0') ||
decoded.split('/').some((segment) => segment === '.' || segment === '..')
) {
throw new Error('Invalid route')
}
} catch {
throw new Error('Invalid route')
}
}
function insertBounded<T>(
map: Map<string, T>,
key: string,
value: T,
max: number
) {
map.delete(key)
map.set(key, value)
while (map.size > max) {
const oldest = map.keys().next().value
if (oldest === undefined) break
map.delete(oldest)
}
}
export class AnalyzeRepository {
private readonly routeCache = new Map<string, Promise<AnalyzeData>>()
private readonly modulesCache = new Map<string, Promise<ModulesData>>()
constructor(private readonly analyzeDir: string) {}
async listSnapshots(): Promise<{
current: SnapshotMetadata
history: SnapshotMetadata[]
}> {
const current = validateMetadata(
await readJson(
path.join(this.analyzeDir, 'data', 'metadata.json'),
'current snapshot metadata'
),
'current snapshot metadata'
)
let history: SnapshotMetadata[] = []
try {
const parsed = (await readJson(
path.join(this.analyzeDir, 'history', 'history.json'),
'snapshot history'
)) as HistoryIndex
if (
!parsed ||
!Array.isArray(parsed.snapshots) ||
parsed.snapshots.length > MAX_HISTORY_ENTRIES
) {
throw new Error('Invalid snapshot history')
}
history = parsed.snapshots
.map((snapshot, index) =>
validateMetadata(snapshot, `snapshot history entry ${index}`)
)
.sort((a, b) => {
if (a.createdAt !== b.createdAt) {
return a.createdAt < b.createdAt ? 1 : -1
}
return a.id < b.id ? 1 : a.id > b.id ? -1 : 0
})
if (
new Set(history.map((snapshot) => snapshot.id)).size !== history.length
) {
throw new Error('Invalid snapshot history')
}
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
}
return { current, history }
}
async getSnapshot(snapshot = 'current'): Promise<SnapshotDataset> {
const snapshots = await this.listSnapshots()
let metadata: SnapshotMetadata
let directory: string
if (snapshot === 'current') {
metadata = snapshots.current
directory = path.join(this.analyzeDir, 'data')
} else {
if (!SNAPSHOT_ID.test(snapshot))
throw new Error('Invalid snapshot identifier')
const match = snapshots.history.find(
(candidate) => candidate.id === snapshot
)
if (!match) throw new Error(`Unknown snapshot: ${snapshot}`)
metadata = match
directory = path.join(this.analyzeDir, 'history', snapshot)
}
assertInside(this.analyzeDir, directory)
const routes = validateStringArray(
await readJson(path.join(directory, 'routes.json'), 'routes.json'),
'routes.json'
)
for (const route of routes) validateRoute(route)
if (routes.length !== metadata.routeCount) {
throw new Error('Invalid routes.json')
}
return { key: snapshot, metadata, routes, directory }
}
async loadRoute(
snapshot: string | undefined,
route: string
): Promise<AnalyzeData> {
validateRoute(route)
const dataset = await this.getSnapshot(snapshot)
if (!dataset.routes.includes(route))
throw new Error(`Unknown route: ${route}`)
const cacheKey = `${dataset.key}\0${route}`
const cached = this.routeCache.get(cacheKey)
if (cached) {
insertBounded(this.routeCache, cacheKey, cached, MAX_ROUTE_DATASETS)
return cached
}
const filename =
route === '/'
? path.join(dataset.directory, 'analyze.data')
: path.join(
dataset.directory,
...route.slice(1).split('/'),
'analyze.data'
)
assertInside(dataset.directory, filename)
const loading = readFile(filename).then(
(contents) => new AnalyzeData(toArrayBuffer(contents))
)
insertBounded(this.routeCache, cacheKey, loading, MAX_ROUTE_DATASETS)
try {
return await loading
} catch (error) {
this.routeCache.delete(cacheKey)
throw error
}
}
async loadModules(snapshot?: string): Promise<ModulesData> {
const dataset = await this.getSnapshot(snapshot)
const cached = this.modulesCache.get(dataset.key)
if (cached) {
insertBounded(this.modulesCache, dataset.key, cached, MAX_MODULE_DATASETS)
return cached
}
const loading = readFile(path.join(dataset.directory, 'modules.data')).then(
(contents) => new ModulesData(toArrayBuffer(contents))
)
insertBounded(this.modulesCache, dataset.key, loading, MAX_MODULE_DATASETS)
try {
return await loading
} catch (error) {
this.modulesCache.delete(dataset.key)
throw error
}
}
}
#!/usr/bin/env node
import * as path from 'node:path'
import { AnalyzeQueryError, queryAnalyzeData } from '../build/analyze/query'
export type NextAnalyzeQueryOptions = {
input?: string
}
function analyzeDir(directory?: string): string {
return path.resolve(directory ?? '.', '.next/diagnostics/analyze')
}
async function printJson(run: () => Promise<unknown>): Promise<void> {
try {
process.stdout.write(`${JSON.stringify(await run())}\n`)
} catch (error) {
const output =
error instanceof AnalyzeQueryError
? error.output
: {
error:
error instanceof Error ? error.message : 'Analyzer query failed',
}
process.stderr.write(`${JSON.stringify(output)}\n`)
process.exitCode = 1
}
}
export async function nextAnalyzeQuery(
tool: string,
directory: string | undefined,
options: NextAnalyzeQueryOptions
): Promise<void> {
return printJson(async () => {
const input: unknown = JSON.parse(options.input ?? '{}')
if (typeof input !== 'object' || input === null || Array.isArray(input)) {
throw new Error('--input must be a JSON object')
}
return queryAnalyzeData(
analyzeDir(directory),
tool,
input as Record<string, unknown>
)
})
}
......@@ -99,6 +99,20 @@ describe('next experimental-analyze', () => {
)
const routes = JSON.parse(routesJson)
expect(routes).toEqual(['/', '/_not-found'])
const query = await next.runCommand([
'experimental-analyze',
'query',
'get_app_overview',
next.testDir,
'--input',
'{"limit":1}',
])
expect(query.exitCode).toBe(0)
expect(JSON.parse(query.stdout)).toMatchObject({
pagination: { limit: 1, returned: 1 },
routes: [{ route: expect.any(String), rawSize: expect.any(Number) }],
})
})
})
})
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment