@timber-js/app 0.1.1 → 0.1.3

package/src/plugins/build-manifest.ts

@@ -0,0 +1,323 @@
+/**
+ * timber-build-manifest — Vite sub-plugin for build asset manifest generation.
+ *
+ * Provides `virtual:timber-build-manifest` which exports a BuildManifest
+ * mapping route segment file paths to their CSS, JS, and modulepreload
+ * output chunks.
+ *
+ * - Dev mode: exports an empty manifest (Vite HMR handles CSS/JS).
+ * - Build mode: virtual module reads from globalThis.__TIMBER_BUILD_MANIFEST__
+ *   at runtime. The actual manifest data is injected by the adapter via a
+ *   _timber-manifest-init.js module that runs before the RSC handler.
+ *
+ * The generateBundle hook (client env only) extracts CSS/JS/modulepreload
+ * data from the Rollup bundle and populates ctx.buildManifest.
+ *
+ * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
+ */
+
+import type { Plugin, ResolvedConfig } from 'vite';
+import type { PluginContext } from '#/index.js';
+import type { BuildManifest } from '#/server/build-manifest.js';
+
+// Rollup types used by generateBundle hook — imported from vite which re-exports them.
+// We define minimal interfaces here to avoid a direct 'rollup' dependency.
+interface OutputChunk {
+  type: 'chunk';
+  fileName: string;
+  facadeModuleId: string | null;
+  imports: string[];
+  name: string;
+  code: string;
+  viteMetadata?: { importedCss?: Set<string> };
+}
+
+interface OutputAsset {
+  type: 'asset';
+  fileName: string;
+}
+
+type OutputBundle = Record<string, OutputChunk | OutputAsset>;
+
+const VIRTUAL_MODULE_ID = 'virtual:timber-build-manifest';
+const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
+
+/**
+ * Vite's manifest.json entry shape (subset we need).
+ * See https://vite.dev/guide/backend-integration.html
+ */
+interface ViteManifestEntry {
+  file: string;
+  css?: string[];
+  imports?: string[];
+}
+
+/**
+ * Parse Vite's .vite/manifest.json into a BuildManifest.
+ *
+ * Walks each entry and collects:
+ * - `css`: CSS output URLs per input file (transitive CSS included by Vite)
+ * - `js`: Hashed JS chunk URL per input file
+ * - `modulepreload`: Transitive JS dependency URLs per input file
+ *
+ * Keys are input file paths (relative to project root).
+ */
+export function parseViteManifest(
+  viteManifest: Record<string, ViteManifestEntry>,
+  base: string
+): BuildManifest {
+  const css: Record<string, string[]> = {};
+  const js: Record<string, string> = {};
+  const modulepreload: Record<string, string[]> = {};
+
+  for (const [inputPath, entry] of Object.entries(viteManifest)) {
+    // JS chunk mapping
+    js[inputPath] = base + entry.file;
+
+    // CSS mapping
+    if (entry.css && entry.css.length > 0) {
+      css[inputPath] = entry.css.map((cssPath) => base + cssPath);
+    }
+
+    // Collect transitive JS dependencies for modulepreload
+    modulepreload[inputPath] = collectTransitiveDeps(inputPath, viteManifest, base);
+  }
+
+  return { css, js, modulepreload, fonts: {} };
+}
+
+/**
+ * Recursively collect transitive JS dependency URLs for an entry.
+ *
+ * Walks the `imports` graph in Vite's manifest, resolving each import
+ * key to its output `file` URL. Deduplicates to avoid cycles and
+ * redundant preloads.
+ */
+function collectTransitiveDeps(
+  entryKey: string,
+  manifest: Record<string, ViteManifestEntry>,
+  base: string
+): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  function walk(key: string) {
+    const entry = manifest[key];
+    if (!entry?.imports) return;
+
+    for (const importKey of entry.imports) {
+      if (seen.has(importKey)) continue;
+      seen.add(importKey);
+
+      const dep = manifest[importKey];
+      if (dep) {
+        result.push(base + dep.file);
+        walk(importKey);
+      }
+    }
+  }
+
+  walk(entryKey);
+  return result;
+}
+
+/**
+ * Build a BuildManifest from a Rollup output bundle.
+ *
+ * Unlike parseViteManifest (which reads Vite's manifest.json), this
+ * works directly with the Rollup bundle output. This is necessary because
+ * the RSC plugin doesn't produce a standard Vite manifest.json.
+ *
+ * Walks each chunk in the bundle and collects:
+ * - `css`: CSS files imported by each chunk (via viteMetadata.importedCss)
+ * - `js`: The output filename for each chunk with a facadeModuleId
+ * - `modulepreload`: Transitive JS imports for each entry chunk
+ *
+ * Keys are input file paths relative to root.
+ */
+export function buildManifestFromBundle(
+  bundle: OutputBundle,
+  base: string,
+  root: string
+): BuildManifest {
+  const css: Record<string, string[]> = {};
+  const js: Record<string, string> = {};
+  const modulepreload: Record<string, string[]> = {};
+
+  // Build a map of chunk fileName → chunk for transitive dep resolution
+  const chunksByFileName = new Map<string, OutputChunk>();
+  for (const item of Object.values(bundle) as (OutputChunk | OutputAsset)[]) {
+    if (item.type === 'chunk') {
+      chunksByFileName.set(item.fileName, item);
+    }
+  }
+
+  for (const item of Object.values(bundle) as (OutputChunk | OutputAsset)[]) {
+    if (item.type !== 'chunk') continue;
+
+    const chunk = item;
+    if (!chunk.facadeModuleId) continue;
+
+    // Convert absolute facadeModuleId to root-relative path
+    let inputPath = chunk.facadeModuleId;
+    if (inputPath.startsWith(root)) {
+      inputPath = inputPath.slice(root.length + 1);
+    }
+
+    // JS chunk mapping
+    js[inputPath] = base + chunk.fileName;
+
+    // CSS mapping via viteMetadata
+    const viteMetadata = chunk.viteMetadata;
+    if (viteMetadata?.importedCss && viteMetadata.importedCss.size > 0) {
+      css[inputPath] = Array.from(viteMetadata.importedCss).map((cssFile) => base + cssFile);
+    }
+
+    // Collect transitive JS dependencies for modulepreload
+    const deps = collectTransitiveBundleDeps(chunk, chunksByFileName, base);
+    if (deps.length > 0) {
+      modulepreload[inputPath] = deps;
+    }
+  }
+
+  // Collect ALL CSS assets from the bundle under the `_global` key.
+  // Route files (app/layout.tsx, app/page.tsx) are server components —
+  // they don't appear in the client bundle, so per-route CSS keying
+  // via facadeModuleId doesn't work. The RSC plugin handles per-route
+  // CSS injection via data-rsc-css-href. For Link headers (103 Early
+  // Hints), we emit all CSS files — they're just prefetch hints.
+  const allCss: string[] = [];
+  for (const item of Object.values(bundle) as (OutputChunk | OutputAsset)[]) {
+    if (item.type === 'asset' && item.fileName.endsWith('.css')) {
+      allCss.push(base + item.fileName);
+    }
+  }
+  if (allCss.length > 0) {
+    css['_global'] = allCss;
+  }
+
+  return { css, js, modulepreload, fonts: {} };
+}
+
+/**
+ * Recursively collect transitive JS dependency URLs from a bundle chunk.
+ */
+function collectTransitiveBundleDeps(
+  chunk: OutputChunk,
+  chunksByFileName: Map<string, OutputChunk>,
+  base: string
+): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  function walk(imports: string[]) {
+    for (const importFileName of imports) {
+      if (seen.has(importFileName)) continue;
+      seen.add(importFileName);
+
+      result.push(base + importFileName);
+      const dep = chunksByFileName.get(importFileName);
+      if (dep) {
+        walk(dep.imports);
+      }
+    }
+  }
+
+  walk(chunk.imports);
+  return result;
+}
+
+/**
+ * Create the timber-build-manifest Vite plugin.
+ *
+ * Hooks: configResolved, resolveId, load, generateBundle (client env only)
+ */
+export function timberBuildManifest(ctx: PluginContext): Plugin {
+  let resolvedBase = '/';
+  let isDev = false;
+
+  return {
+    name: 'timber-build-manifest',
+
+    configResolved(config: ResolvedConfig) {
+      resolvedBase = config.base;
+      isDev = config.command === 'serve';
+    },
+
+    resolveId(id: string) {
+      const cleanId = id.startsWith('\0') ? id.slice(1) : id;
+
+      if (cleanId === VIRTUAL_MODULE_ID) {
+        return RESOLVED_VIRTUAL_ID;
+      }
+
+      if (cleanId.endsWith(`/${VIRTUAL_MODULE_ID}`)) {
+        return RESOLVED_VIRTUAL_ID;
+      }
+
+      return null;
+    },
+
+    load(id: string) {
+      if (id !== RESOLVED_VIRTUAL_ID) return null;
+
+      // In dev mode, return empty manifest — Vite HMR handles CSS.
+      if (isDev) {
+        return [
+          '// Auto-generated build manifest — do not edit.',
+          '// Dev mode: empty manifest (Vite HMR handles CSS/JS).',
+          '',
+          'const manifest = { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+          '',
+          'export default manifest;',
+        ].join('\n');
+      }
+
+      // In production, read from globalThis at runtime.
+      // The adapter writes a _timber-manifest-init.js that sets this global
+      // before the RSC handler imports this module. ESM evaluation order
+      // guarantees the global is set by the time this code runs.
+      return [
+        '// Auto-generated build manifest — do not edit.',
+        '// Production: reads manifest from globalThis (set by _timber-manifest-init.js).',
+        '',
+        'const manifest = globalThis.__TIMBER_BUILD_MANIFEST__ ?? { css: {}, js: {}, modulepreload: {}, fonts: {} };',
+        '',
+        'export default manifest;',
+      ].join('\n');
+    },
+
+    // Extract manifest data from the client bundle only.
+    // The RSC plugin runs builds in order: RSC → client → SSR.
+    // We only want client env data (CSS assets, client JS chunks).
+    generateBundle(_options, bundle) {
+      if (isDev) return;
+
+      const envName = (this as { environment?: { name: string } }).environment?.name;
+
+      if (envName === 'client') {
+        ctx.buildManifest = buildManifestFromBundle(bundle, resolvedBase, ctx.root);
+
+        // When client JavaScript is disabled, strip JS chunks from the bundle
+        // so Rollup never writes them to disk. CSS assets are preserved —
+        // they're still needed for server-rendered HTML.
+        //
+        // This is an optimization: adapter-build.ts still strips JS from the
+        // build manifest and RSC assets manifest as a defense-in-depth fallback.
+        if (ctx.clientJavascript.disabled) {
+          // Clear JS and modulepreload from the manifest (they'd be stripped
+          // by adapter-build.ts anyway, but doing it here avoids the round-trip).
+          ctx.buildManifest.js = {};
+          ctx.buildManifest.modulepreload = {};
+
+          // Remove JS chunks from the Rollup bundle — prevents disk writes.
+          for (const [fileName, item] of Object.entries(bundle)) {
+            if (item.type === 'chunk') {
+              delete bundle[fileName];
+            }
+          }
+        }
+      }
+    },
+  };
+}

package/src/plugins/build-report.ts

@@ -0,0 +1,353 @@
+/**
+ * timber-build-report — Post-build route summary table.
+ *
+ * After a production build, logs a per-route table showing:
+ * - Route type (○ static, λ dynamic, ƒ function)
+ * - Route-specific client JS size
+ * - First-load JS size (gzip) — route-specific + shared chunks
+ *
+ * Only active during production builds. Sizes are computed from the
+ * already-generated Vite client bundle — no extra analysis passes.
+ *
+ * Design docs: 18-build-system.md §"Build Pipeline", 07-routing.md
+ * Task: TIM-287
+ */
+
+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';
+
+// ─── Public types ─────────────────────────────────────────────────────────
+
+export type RouteType = 'static' | 'dynamic' | 'function';
+
+export interface RouteEntry {
+  path: string;
+  type: RouteType;
+  /** Route-specific client JS size in bytes (raw). */
+  size: number;
+  /** Total first-load JS in bytes (gzip): route-specific + shared. */
+  firstLoadSize: number;
+}
+
+// ─── Route classification ─────────────────────────────────────────────────
+
+const ROUTE_TYPE_ICONS: Record<RouteType, string> = {
+  static: '○',
+  dynamic: 'λ',
+  function: 'ƒ',
+};
+
+/**
+ * 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.
+ */
+export function classifyRoute(
+  segments: SegmentNode[],
+  outputMode: 'server' | 'static' = 'server'
+): RouteType {
+  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';
+}
+
+// ─── Size helpers ─────────────────────────────────────────────────────────
+
+export { formatSize };
+
+function green(text: string): string {
+  return `\x1b[92m${text}\x1b[39m`; // bright/light green (ANSI 92)
+}
+
+// ─── Route tree collection ────────────────────────────────────────────────
+
+interface RouteInfo {
+  path: string;
+  segments: SegmentNode[];
+  entryFilePath: string | null;
+}
+
+/** Walk the route tree and collect all leaf routes (pages + API endpoints). */
+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 });
+    }
+
+    for (const child of node.children) walk(child, currentChain);
+    for (const slot of node.slots.values()) walk(slot, currentChain);
+  }
+
+  walk(tree.root, []);
+  return routes;
+}
+
+// ─── Report formatting ────────────────────────────────────────────────────
+
+/** Produce formatted report lines for the Vite logger. */
+export function buildRouteReport(entries: RouteEntry[], sharedSize: number): string[] {
+  const sorted = [...entries].sort((a, b) => a.path.localeCompare(b.path));
+
+  const header = 'Route (app)';
+  const sizeHeader = 'Size';
+  const firstLoadHeader = 'First Load JS';
+
+  const pathW = Math.max(header.length + 2, ...sorted.map((e) => e.path.length + 6));
+  const sizeW = Math.max(sizeHeader.length, 14);
+  const flW = Math.max(firstLoadHeader.length, 10);
+  const totalW = pathW + sizeW + flW + 4;
+  const sep = '─'.repeat(totalW);
+
+  const lines: string[] = [];
+
+  // Header
+  lines.push(
+    `${pad(header, pathW)}  ${pad(sizeHeader, sizeW, 'left')}  ${pad(firstLoadHeader, flW, 'left')}`
+  );
+  lines.push(sep);
+
+  // Routes
+  for (const entry of sorted) {
+    const icon = ROUTE_TYPE_ICONS[entry.type];
+    const pathStr = `  ${icon} ${entry.path}`;
+    const sizeStr = entry.size === 0 ? green('zero unique JS') : formatSize(entry.size);
+    const flStr = formatSize(entry.firstLoadSize);
+    lines.push(
+      `${pad(pathStr, pathW)}  ${pad(sizeStr, sizeW, 'left')}  ${pad(flStr, flW, 'left')}`
+    );
+  }
+
+  // Footer
+  lines.push(sep);
+  lines.push(
+    `${pad('  Shared by all', pathW)}  ${pad('', sizeW, 'left')}  ${pad(formatSize(sharedSize), flW, 'left')}`
+  );
+  lines.push('');
+  lines.push('○  (Static)   λ  (Dynamic)   ƒ  (Function)');
+
+  return lines;
+}
+
+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);
+}
+
+function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\u001b\[\d+m/g, '');
+}
+
+// ─── Bundle analysis ──────────────────────────────────────────────────────
+
+interface ChunkSize {
+  raw: number;
+  gzip: number;
+}
+
+interface OutputChunkLike {
+  type: 'chunk' | 'asset';
+  fileName: string;
+  code?: string;
+  source?: string | Uint8Array;
+  modules?: Record<string, unknown>;
+  facadeModuleId?: string | null;
+}
+
+/** Measure raw + gzip sizes for all JS chunks and CSS assets in a bundle. */
+export function collectChunkSizes(bundle: Record<string, OutputChunkLike>): Map<string, ChunkSize> {
+  const sizes = new Map<string, ChunkSize>();
+  for (const [fileName, item] of Object.entries(bundle)) {
+    if (item.type === 'chunk' && item.code) {
+      sizes.set(fileName, measure(item.code));
+    } else if (item.type === 'asset' && fileName.endsWith('.css') && item.source != null) {
+      const src =
+        typeof item.source === 'string' ? item.source : new TextDecoder().decode(item.source);
+      sizes.set(fileName, measure(src));
+    }
+  }
+  return sizes;
+}
+
+function measure(content: string): ChunkSize {
+  const buf = new TextEncoder().encode(content);
+  return { raw: buf.length, gzip: gzipSync(buf).length };
+}
+
+/** Find the output chunk that contains a given input file. */
+export function findChunkForFile(
+  filePath: string,
+  bundle: Record<string, OutputChunkLike>
+): string | null {
+  for (const [fileName, item] of Object.entries(bundle)) {
+    if (item.type !== 'chunk') continue;
+    if (item.facadeModuleId === filePath) return fileName;
+    if (item.modules && filePath in item.modules) return fileName;
+  }
+  return null;
+}
+
+// ─── Build route entries from collected data ──────────────────────────────
+
+function buildEntries(
+  routeTree: RouteTree,
+  chunkSizes: Map<string, ChunkSize>,
+  bundle: Record<string, OutputChunkLike>,
+  outputMode: 'server' | 'static'
+): { entries: RouteEntry[]; sharedGzip: number } {
+  const routeInfos = collectRoutes(routeTree);
+
+  // Total gzip across all client chunks
+  let totalGzip = 0;
+  for (const s of chunkSizes.values()) totalGzip += s.gzip;
+
+  // Per-route sizes and track route-specific chunks
+  const routeChunkFiles = new Set<string>();
+  const entries: RouteEntry[] = [];
+
+  for (const info of routeInfos) {
+    let raw = 0;
+    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;
+        }
+        routeChunkFiles.add(chunk);
+      }
+    }
+
+    entries.push({
+      path: info.path,
+      type: classifyRoute(info.segments, outputMode),
+      size: raw,
+      firstLoadSize: gzip, // route-specific gzip — shared added below
+    });
+  }
+
+  // Shared = total gzip minus route-specific gzip
+  let routeGzip = 0;
+  for (const f of routeChunkFiles) routeGzip += chunkSizes.get(f)?.gzip ?? 0;
+  const sharedGzip = totalGzip - routeGzip;
+
+  for (const e of entries) e.firstLoadSize += sharedGzip;
+
+  return { entries, sharedGzip };
+}
+
+// ─── Vite plugin ──────────────────────────────────────────────────────────
+
+/**
+ * Suppress RSC/SSR per-chunk build log lines.
+ *
+ * Vite logs each output chunk via config.logger.info(). We wrap that method
+ * to filter lines matching dist/rsc/ or dist/ssr/ paths. The regex is
+ * non-anchored because Vite prepends ANSI color codes.
+ */
+function suppressNonClientLogs(config: { command: string; logger: Logger }): void {
+  if (config.command !== 'build') return;
+  const orig = config.logger.info.bind(config.logger);
+  config.logger.info = (msg: string, opts?: { timestamp?: boolean }) => {
+    if (typeof msg === 'string' && /dist\/(rsc|ssr)\//.test(msg)) return;
+    orig(msg, opts);
+  };
+}
+
+export function timberBuildReport(ctx: PluginContext): Plugin {
+  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();
+
+  return {
+    name: 'timber-build-report',
+
+    config(_cfg, { command }) {
+      if (command !== 'build') return;
+      return {
+        environments: {
+          rsc: { build: { reportCompressedSize: false } },
+          ssr: { build: { reportCompressedSize: false } },
+        },
+      };
+    },
+
+    configResolved(config) {
+      logger = config.logger;
+      suppressNonClientLogs(config);
+    },
+
+    generateBundle(_options, bundle) {
+      if (ctx.dev) return;
+      if (this.environment?.name && this.environment.name !== 'client') return;
+
+      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('');
+    },
+  };
+}