@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/plugins/build-report.ts

@@ -13,11 +13,17 @@
  * Task: TIM-287
  */
 
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { SegmentNode, RouteTree } from '#/routing/types.js';
-import { formatSize } from '#/utils/format.js';
+import type { PluginContext } from '../plugin-context.ts';
+import type { SegmentNode, RouteTree } from '../routing/types.ts';
+import type { CaptureSummary } from '../server/prebuilt-builder.ts';
+import type { PrebuiltCaptureResult } from './prebuilt-capture.ts';
+import type { PrebuiltManifest } from '../server/prebuilt/payload-source.ts';
+import { collectLeafRoutes } from '../routing/walkers.ts';
+import { formatSize } from '../utils/format.ts';
 
 // ─── Public types ─────────────────────────────────────────────────────────
 
@@ -43,25 +49,19 @@ const ROUTE_TYPE_ICONS: Record<RouteType, string> = {
 /**
  * Classify a route by its segment chain and output mode.
  *
- * In server mode (default), all pages are dynamic (rendered per-request).
- * In static mode, only pages with dynamic/catch-all segments are dynamic.
- * API routes (route.ts) are always classified as function.
+ * In server mode (default), all pages are dynamic (rendered per-request)
+ * and API routes (route.ts) are classified as function.
+ * In static mode, everything is pre-rendered at build time — all routes
+ * are static regardless of dynamic segments or route.ts presence.
  */
 export function classifyRoute(
   segments: SegmentNode[],
   outputMode: 'server' | 'static' = 'server'
 ): RouteType {
+  if (outputMode === 'static') return 'static';
   const leaf = segments[segments.length - 1];
   if (leaf?.route) return 'function';
-  if (outputMode === 'server') return 'dynamic';
-
-  const isDynamic = segments.some(
-    (s) =>
-      s.segmentType === 'dynamic' ||
-      s.segmentType === 'catch-all' ||
-      s.segmentType === 'optional-catch-all'
-  );
-  return isDynamic ? 'dynamic' : 'static';
+  return 'dynamic';
 }
 
 // ─── Size helpers ─────────────────────────────────────────────────────────
@@ -83,33 +83,23 @@ interface RouteInfo {
 /**
  * Walk the route tree and collect all leaf routes (pages + API endpoints).
  *
- * Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
- * they render alongside the parent page at the same URL and are not
- * separately URL-addressable. Their JS is captured in shared/layout chunks.
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Parallel slots
+ * (`@artists`, `@shows`, etc.) are intentionally skipped — they render
+ * alongside the parent page at the same URL and are not separately
+ * URL-addressable. Their JS is captured in shared/layout chunks.
  *
  * After collection, entries are deduplicated by URL path so that overlapping
  * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
- * appear once. The entry with the largest route-specific size wins.
+ * appear once. The entry with the longest segment chain (most specific
+ * match) wins.
  */
 export function collectRoutes(tree: RouteTree): RouteInfo[] {
-  const routes: RouteInfo[] = [];
-
-  function walk(node: SegmentNode, chain: SegmentNode[]): void {
-    const currentChain = [...chain, node];
-    const path = node.urlPath || '/';
-
-    if (node.page) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.page.filePath });
-    }
-    if (node.route) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.route.filePath });
-    }
-
-    // Recurse into child segments only — skip parallel slots (node.slots)
-    for (const child of node.children) walk(child, currentChain);
-  }
-
-  walk(tree.root, []);
+  const leaves = collectLeafRoutes(tree.root);
+  const routes: RouteInfo[] = leaves.map((leaf) => ({
+    path: leaf.urlPath,
+    segments: leaf.segments,
+    entryFilePath: leaf.page?.filePath ?? leaf.route?.filePath ?? null,
+  }));
 
   // Deduplicate entries with the same URL path (e.g. from overlapping route groups).
   // Keep the entry with the longest segment chain (most specific match).
@@ -169,6 +159,21 @@ export function buildRouteReport(entries: RouteEntry[], sharedSize: number): str
   return lines;
 }
 
+/** Check route entries against a First-Load-JS budget and return warning lines. */
+export function buildWarnings(entries: RouteEntry[], budget?: { firstLoadJs?: number }): string[] {
+  if (!budget?.firstLoadJs) return [];
+  const limit = budget.firstLoadJs;
+  const warnings: string[] = [];
+  for (const entry of entries) {
+    if (entry.firstLoadSize > limit) {
+      warnings.push(
+        `⚠ ${entry.path} first-load JS (${formatSize(entry.firstLoadSize)}) exceeds budget (${formatSize(limit)})`
+      );
+    }
+  }
+  return warnings;
+}
+
 function pad(str: string, width: number, align: 'left' | 'right' = 'right'): string {
   const gap = Math.max(0, width - stripAnsi(str).length);
   return align === 'left' ? ' '.repeat(gap) + str : str + ' '.repeat(gap);
@@ -179,6 +184,117 @@ function stripAnsi(str: string): string {
   return str.replace(/\u001b\[\d+m/g, '');
 }
 
+// ─── Prebuilt component stats ────────────────────────────────────────────
+
+export interface PrebuiltComponentStats {
+  componentId: string;
+  entryCount: number;
+  totalBytes: number;
+}
+
+export interface PrebuiltReportData {
+  components: PrebuiltComponentStats[];
+  totalEntries: number;
+  totalBytes: number;
+  skippedCount: number;
+  skippedReasons: Array<{ componentId: string; route: string; message: string }>;
+}
+
+/** Read the manifest of the prebuilt artifact this build recorded, if any. */
+export function loadPrebuiltManifest(prebuiltDir: string | undefined): PrebuiltManifest | null {
+  if (!prebuiltDir) return null;
+  return JSON.parse(readFileSync(join(prebuiltDir, 'manifest.json'), 'utf-8')) as PrebuiltManifest;
+}
+
+export function buildPrebuiltReportData(
+  manifest: PrebuiltManifest | null,
+  summary: CaptureSummary | undefined
+): PrebuiltReportData | null {
+  const hasCaptures = summary && (summary.captured > 0 || summary.skipped.length > 0);
+  if (!manifest && !hasCaptures) return null;
+
+  const components: PrebuiltComponentStats[] = [];
+  let totalEntries = 0;
+  let totalBytes = 0;
+
+  if (manifest) {
+    for (const [componentId, component] of Object.entries(manifest)) {
+      let entryCount = 0;
+      let componentBytes = 0;
+      for (const entry of Object.values(component.entries)) {
+        entryCount++;
+        componentBytes += entry.bytes ?? 0;
+      }
+      components.push({ componentId, entryCount, totalBytes: componentBytes });
+      totalEntries += entryCount;
+      totalBytes += componentBytes;
+    }
+    components.sort((a, b) => a.componentId.localeCompare(b.componentId));
+  }
+
+  const skippedCount = summary?.skipped.length ?? 0;
+  const skippedReasons = (summary?.skipped ?? []).map((s) => ({
+    componentId: s.componentId,
+    route: s.routeUrlPath,
+    message: s.message,
+  }));
+
+  return { components, totalEntries, totalBytes, skippedCount, skippedReasons };
+}
+
+export function buildPrebuiltReport(data: PrebuiltReportData): string[] {
+  const lines: string[] = [];
+
+  const total = data.totalEntries + data.skippedCount;
+  lines.push(
+    `Prebuilt ${data.totalEntries}/${total} entries across ` +
+      `${data.components.length} component${data.components.length !== 1 ? 's' : ''}` +
+      (data.totalBytes > 0 ? ` (${formatSize(data.totalBytes)} total)` : '') +
+      '.' +
+      (data.skippedCount > 0 ? ` ${data.skippedCount} skipped due to errors.` : '')
+  );
+
+  if (data.components.length > 0) {
+    lines.push('');
+    const nameHeader = 'Component';
+    const entriesHeader = 'Entries';
+    const sizeHeader = 'Size';
+
+    const nameW = Math.max(
+      nameHeader.length + 2,
+      ...data.components.map((c) => c.componentId.length + 4)
+    );
+    const entriesW = Math.max(entriesHeader.length, 8);
+    const sizeW = Math.max(sizeHeader.length, 10);
+    const totalW = nameW + entriesW + sizeW + 4;
+    const sep = '─'.repeat(totalW);
+
+    lines.push(
+      `${pad(nameHeader, nameW)}  ${pad(entriesHeader, entriesW, 'left')}  ${pad(sizeHeader, sizeW, 'left')}`
+    );
+    lines.push(sep);
+
+    for (const comp of data.components) {
+      const nameStr = `  ◆ ${comp.componentId}`;
+      const entriesStr = String(comp.entryCount);
+      const sizeStr = formatSize(comp.totalBytes);
+      lines.push(
+        `${pad(nameStr, nameW)}  ${pad(entriesStr, entriesW, 'left')}  ${pad(sizeStr, sizeW, 'left')}`
+      );
+    }
+  }
+
+  if (data.skippedReasons.length > 0) {
+    lines.push('');
+    lines.push('Skipped entries:');
+    for (const s of data.skippedReasons) {
+      lines.push(`  ⚠ ${s.componentId} (${s.route}) — ${s.message}`);
+    }
+  }
+
+  return lines;
+}
+
 // ─── Bundle analysis ──────────────────────────────────────────────────────
 
 interface ChunkSize {
@@ -189,6 +305,7 @@ interface ChunkSize {
 interface OutputChunkLike {
   type: 'chunk' | 'asset';
   fileName: string;
+  name?: string;
   code?: string;
   source?: string | Uint8Array;
   modules?: Record<string, unknown>;
@@ -228,13 +345,62 @@ export function findChunkForFile(
   return null;
 }
 
+// ─── Route → chunk group matching ────────────────────────────────────────
+
+/**
+ * Derive the expected client chunk group prefix for a route.
+ *
+ * Mirrors the `clientChunkGroup` logic: extract the first non-group segment
+ * from the route's file path under appDir. Routes at the root level or
+ * without a matching segment return null (their JS is in client-shared).
+ */
+function routeChunkGroupPrefix(entryFilePath: string, appDir: string, root: string): string | null {
+  const appPrefix = relative(root, appDir).replace(/\\/g, '/') + '/';
+  const relPath = relative(root, entryFilePath).replace(/\\/g, '/');
+  if (!relPath.startsWith(appPrefix)) return null;
+
+  const withinApp = relPath.slice(appPrefix.length);
+  const segments = withinApp.split('/');
+  for (const seg of segments) {
+    if (seg.includes('.')) break;
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    return `client-${seg}`;
+  }
+  return null;
+}
+
+/**
+ * Find all client bundle chunks belonging to a chunk group.
+ *
+ * Uses the chunk's `name` property (set by Rolldown from the `clientChunks`
+ * callback's return value) for exact matching. The `name` is the group name
+ * itself (e.g. `client-docs`), not the hashed filename.
+ */
+export function findChunksForGroup(
+  groupName: string,
+  chunkSizes: Map<string, ChunkSize>,
+  bundle?: Record<string, OutputChunkLike>
+): string[] {
+  if (!bundle) return [];
+  const matched: string[] = [];
+  for (const [fileName, item] of Object.entries(bundle)) {
+    if (item.type !== 'chunk') continue;
+    if (item.name === groupName && chunkSizes.has(fileName)) {
+      matched.push(fileName);
+    }
+  }
+  return matched;
+}
+
 // ─── Build route entries from collected data ──────────────────────────────
 
 function buildEntries(
   routeTree: RouteTree,
   chunkSizes: Map<string, ChunkSize>,
   bundle: Record<string, OutputChunkLike>,
-  outputMode: 'server' | 'static'
+  outputMode: 'server' | 'static',
+  appDir?: string,
+  root?: string
 ): { entries: RouteEntry[]; sharedGzip: number } {
   const routeInfos = collectRoutes(routeTree);
 
@@ -242,7 +408,7 @@ function buildEntries(
   let totalGzip = 0;
   for (const s of chunkSizes.values()) totalGzip += s.gzip;
 
-  // Per-route sizes and track route-specific chunks
+  // Per-route sizes. Track route-specific chunks to compute shared size.
   const routeChunkFiles = new Set<string>();
   const entries: RouteEntry[] = [];
 
@@ -251,14 +417,36 @@ function buildEntries(
     let gzip = 0;
 
     if (info.entryFilePath) {
-      const chunk = findChunkForFile(info.entryFilePath, bundle);
-      if (chunk) {
-        const s = chunkSizes.get(chunk);
-        if (s) {
-          raw = s.raw;
-          gzip = s.gzip;
+      // Try chunk group matching first (works for server component routes
+      // whose client JS is in client-<segment> chunks, not in the route's
+      // own page.tsx chunk). Falls back to direct chunk lookup.
+      let matched = false;
+      if (appDir && root) {
+        const groupPrefix = routeChunkGroupPrefix(info.entryFilePath, appDir, root);
+        if (groupPrefix) {
+          const chunks = findChunksForGroup(groupPrefix, chunkSizes, bundle);
+          for (const chunk of chunks) {
+            const s = chunkSizes.get(chunk);
+            if (s) {
+              raw += s.raw;
+              gzip += s.gzip;
+            }
+            routeChunkFiles.add(chunk);
+          }
+          if (chunks.length > 0) matched = true;
+        }
+      }
+
+      if (!matched) {
+        const chunk = findChunkForFile(info.entryFilePath, bundle);
+        if (chunk) {
+          const s = chunkSizes.get(chunk);
+          if (s) {
+            raw = s.raw;
+            gzip = s.gzip;
+          }
+          routeChunkFiles.add(chunk);
         }
-        routeChunkFiles.add(chunk);
       }
     }
 
@@ -298,17 +486,79 @@ function suppressNonClientLogs(config: { command: string; logger: Logger }): voi
   };
 }
 
-export function timberBuildReport(ctx: PluginContext): Plugin {
+/**
+ * What the post-build phase asks of the build report (plugins/post-build.ts).
+ * Printed from there, once, after every environment is built and after the
+ * prebuilt capture pass — so nothing here depends on the order in which
+ * Vite closes each environment's bundle.
+ */
+export interface BuildReportStep {
+  print(prebuilt: PrebuiltCaptureResult | null): void;
+}
+
+export function timberBuildReport(ctx: PluginContext): Plugin & { api: BuildReportStep } {
   let logger: Logger | null = null;
   let chunkSizes: Map<string, ChunkSize> | null = null;
   let clientBundle: Record<string, OutputChunkLike> | null = null;
-  let reported = false;
-  let deferReport = false;
   const buildStart = performance.now();
 
+  function printRouteTable(): void {
+    if (!ctx.routeTree || !chunkSizes || !clientBundle || !logger) return;
+
+    const outputMode = ctx.config.output ?? 'server';
+    const clientJsDisabled = ctx.clientJavascript.disabled;
+    const { entries, sharedGzip } = clientJsDisabled
+      ? {
+          entries: collectRoutes(ctx.routeTree).map((info) => ({
+            path: info.path,
+            type: classifyRoute(info.segments, outputMode),
+            size: 0,
+            firstLoadSize: 0,
+          })),
+          sharedGzip: 0,
+        }
+      : buildEntries(ctx.routeTree, chunkSizes, clientBundle, outputMode, ctx.appDir, ctx.root);
+    const elapsed = ((performance.now() - buildStart) / 1000).toFixed(2);
+    const lines = buildRouteReport(entries, sharedGzip);
+
+    logger.info('');
+    for (const line of lines) logger.info(line);
+
+    const warnings = buildWarnings(entries, ctx.config.budget);
+    if (warnings.length > 0) {
+      logger.info('');
+      for (const w of warnings) logger.warn(w);
+    }
+
+    logger.info('');
+    logger.info(
+      `✓ built ${entries.length} routes for all three environments (rsc, ssr, client) in ${elapsed}s`
+    );
+    logger.info('');
+  }
+
+  function printPrebuiltReport(prebuilt: PrebuiltCaptureResult | null): void {
+    if (!logger || !prebuilt) return;
+    const manifest = loadPrebuiltManifest(prebuilt.artifact?.path);
+    const prebuiltData = buildPrebuiltReportData(manifest, prebuilt.summary);
+    if (!prebuiltData) return;
+
+    logger.info('');
+    for (const line of buildPrebuiltReport(prebuiltData)) logger.info(line);
+    logger.info('');
+  }
+
   return {
     name: 'timber-build-report',
 
+    api: {
+      print(prebuilt) {
+        if (ctx.dev) return;
+        printRouteTable();
+        printPrebuiltReport(prebuilt);
+      },
+    },
+
     config(_cfg, { command }) {
       if (command !== 'build') return;
       return {
@@ -330,44 +580,6 @@ export function timberBuildReport(ctx: PluginContext): Plugin {
 
       chunkSizes = collectChunkSizes(bundle as Record<string, OutputChunkLike>);
       clientBundle = { ...bundle } as Record<string, OutputChunkLike>;
-      deferReport = true; // skip client's closeBundle; emit after SSR's
-    },
-
-    closeBundle() {
-      if (ctx.dev || reported) return;
-
-      // The client build's closeBundle fires before SSR starts.
-      // Defer one cycle so the report appears after all builds complete.
-      if (deferReport) {
-        deferReport = false;
-        return;
-      }
-      if (!ctx.routeTree || !chunkSizes || !clientBundle || !logger) return;
-
-      reported = true;
-      const outputMode = ctx.config.output ?? 'server';
-      const clientJsDisabled = ctx.clientJavascript.disabled;
-      const { entries, sharedGzip } = clientJsDisabled
-        ? {
-            entries: collectRoutes(ctx.routeTree).map((info) => ({
-              path: info.path,
-              type: classifyRoute(info.segments, outputMode),
-              size: 0,
-              firstLoadSize: 0,
-            })),
-            sharedGzip: 0,
-          }
-        : buildEntries(ctx.routeTree, chunkSizes, clientBundle, outputMode);
-      const elapsed = ((performance.now() - buildStart) / 1000).toFixed(2);
-      const lines = buildRouteReport(entries, sharedGzip);
-
-      logger.info('');
-      for (const line of lines) logger.info(line);
-      logger.info('');
-      logger.info(
-        `✓ built ${entries.length} routes for all three environments (rsc, ssr, client) in ${elapsed}s`
-      );
-      logger.info('');
     },
   };
 }