Report Generation

/**
 * Generates static HTML report with embedded bundle visualization
 * @param bundleStats - Webpack stats object
 * @param options - Report generation options
 */
function generateReport(
  bundleStats: object,
  options?: ReportOptions
): Promise<void>;

interface ReportOptions {
  /** Whether to automatically open report in browser */
  openBrowser?: boolean;
  /** Output file path for HTML report */
  reportFilename: string;
  /** Report title (string or function returning string) */
  reportTitle?: string | (() => string);
  /** Directory containing bundle files for size analysis */
  bundleDir?: string;
  /** Logger instance for output messages */
  logger?: Logger;
  /** Default size type to display in visualization */
  defaultSizes?: 'stat' | 'parsed' | 'gzip';
  /** Patterns to exclude assets from report */
  excludeAssets?: string | RegExp | ((assetName: string) => boolean) | Array<string | RegExp | ((assetName: string) => boolean)>;
}

const { generateReport } = require('webpack-bundle-analyzer/lib/viewer');
const fs = require('fs');

// Load webpack stats
const stats = JSON.parse(fs.readFileSync('stats.json'));

// Basic HTML report
await generateReport(stats, {
  reportFilename: 'bundle-report.html'
});

// Customized report
await generateReport(stats, {
  reportFilename: './reports/production-bundle.html',
  reportTitle: 'Production Bundle Analysis',
  bundleDir: './dist',
  defaultSizes: 'gzip',
  openBrowser: false,
  excludeAssets: /\.css$/
});

// Dynamic title with timestamp
await generateReport(stats, {
  reportFilename: 'bundle-report.html',
  reportTitle: () => `Bundle Report - ${new Date().toISOString()}`
});

/**
 * Generates JSON report with bundle analysis data
 * @param bundleStats - Webpack stats object
 * @param options - JSON report options
 */
function generateJSONReport(
  bundleStats: object,
  options?: JSONReportOptions
): Promise<void>;

interface JSONReportOptions {
  /** Output file path for JSON report */
  reportFilename: string;
  /** Directory containing bundle files for size analysis */
  bundleDir?: string;
  /** Logger instance for output messages */
  logger?: Logger;
  /** Patterns to exclude assets from report */
  excludeAssets?: string | RegExp | ((assetName: string) => boolean) | Array<string | RegExp | ((assetName: string) => boolean)>;
}

const { generateJSONReport } = require('webpack-bundle-analyzer/lib/viewer');

// Basic JSON report
await generateJSONReport(stats, {
  reportFilename: 'bundle-data.json'
});

// Customized JSON report
await generateJSONReport(stats, {
  reportFilename: './data/bundle-analysis.json',
  bundleDir: './dist',
  excludeAssets: ['vendor', /\.css$/]
});

/**
 * Starts HTTP server with interactive bundle visualization
 * @param bundleStats - Webpack stats object
 * @param options - Server configuration options
 * @returns Server instance with update capabilities
 */
function startServer(
  bundleStats: object,
  options?: ServerOptions
): Promise<ServerInstance>;

interface ServerOptions {
  /** Server port number or 'auto' for automatic assignment */
  port?: number | 'auto';
  /** Server host address */
  host?: string;
  /** Whether to automatically open browser */
  openBrowser?: boolean;
  /** Directory containing bundle files */
  bundleDir?: string;
  /** Logger instance */
  logger?: Logger;
  /** Default size type to display */
  defaultSizes?: 'stat' | 'parsed' | 'gzip';
  /** Asset exclusion patterns */
  excludeAssets?: string | RegExp | ((assetName: string) => boolean) | Array<string | RegExp | ((assetName: string) => boolean)>;
  /** Report title */
  reportTitle?: string | (() => string);
  /** Custom URL generation function */
  analyzerUrl?: (options: { listenHost: string; listenPort: number; boundAddress: object }) => string;
}

interface ServerInstance {
  /** WebSocket server for live updates */
  ws: object;
  /** HTTP server instance */
  http: object;
  /** Update chart data and notify connected clients */
  updateChartData: (bundleStats: object) => void;
}

const { startServer } = require('webpack-bundle-analyzer/lib/viewer');

// Basic server
const server = await startServer(stats);

// Custom server configuration
const server = await startServer(stats, {
  port: 9999,
  host: '0.0.0.0',
  openBrowser: false,
  bundleDir: './dist',
  defaultSizes: 'gzip'
});

// Update data (useful for webpack watch mode)
const newStats = getUpdatedStats();
server.updateChartData(newStats);

/**
 * Renders HTML report using template system
 * @param options - Template rendering options
 * @returns Complete HTML string
 */
function renderViewer(options: TemplateOptions): string;

interface TemplateOptions {
  /** Report title for HTML title tag */
  title?: string;
  /** Enable WebSocket connection for live updates */
  enableWebSocket?: boolean;
  /** Bundle analysis data for visualization */
  chartData: object;
  /** Webpack entrypoint information */
  entrypoints: string[];
  /** Default size type to display */
  defaultSizes?: 'stat' | 'parsed' | 'gzip';
  /** Template mode: 'server' for dynamic assets, 'static' for embedded */
  mode: 'server' | 'static';
}

/**
 * Extracts entrypoint names from webpack stats
 * @param bundleStats - Webpack stats object
 * @returns Array of entrypoint names
 */
function getEntrypoints(bundleStats: object): string[];

const { getEntrypoints } = require('webpack-bundle-analyzer/lib/viewer');

const entrypoints = getEntrypoints(stats);
console.log('Available entrypoints:', entrypoints);
// Output: ['main', 'vendor', 'runtime']

/**
 * Opens URL in default browser with error handling
 * @param uri - URL to open
 * @param logger - Logger for error messages
 */
function open(uri: string, logger: Logger): void;

// Reports with nested directory structure
await generateReport(stats, {
  reportFilename: './reports/production/bundle-analysis.html'
});

await generateJSONReport(stats, {
  reportFilename: './data/analysis/bundle-data.json'
});

// Static title
reportTitle: 'Production Bundle Analysis'

// Dynamic title with build info
reportTitle: () => `Bundle Analysis - Build ${process.env.BUILD_NUMBER}`

// Date-based title
reportTitle: () => `Bundle Report - ${new Date().toLocaleDateString()}`

// Show original source sizes
defaultSizes: 'stat'

// Show minified bundle sizes (default)
defaultSizes: 'parsed'

// Show compressed transfer sizes
defaultSizes: 'gzip'

// Exclude development assets
excludeAssets: /\.(map|test\.js)$/

// Exclude by name pattern
excludeAssets: 'hot-update'

// Complex filtering logic
excludeAssets: (assetName) => {
  return assetName.includes('dev') || 
         assetName.includes('test') ||
         assetName.endsWith('.map');
}