@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.149

package/src/plugins/routing.ts

@@ -10,24 +10,25 @@
 
 import type { Plugin, ViteDevServer } from 'vite';
 import { writeFile, mkdir } from 'node:fs/promises';
-import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { scanRoutes } from '../routing/scanner.js';
 import { generateRouteMap } from '../routing/codegen.js';
-import { collectInterceptionRewrites } from '../routing/interception.js';
 import {
   buildDirToRouteMap,
   writeSegmentTypes,
   type SegmentInfo,
 } from '../routing/segment-codegen.js';
 import { validateSchemaAgainstRoutes } from '../routing/schema-validation.js';
-
+import {
+  generateManifestModule,
+  generateSearchParamsRegistryModule,
+  generateSchemaModule,
+} from '../routing/manifest-codegen.js';
 import {
   lintConventions,
   checkAppDirExists,
   formatConventionWarnings,
 } from '../routing/convention-lint.js';
-import type { RouteTree, SegmentNode, RouteFile } from '../routing/types.js';
 import type { PluginContext } from '../plugin-context.js';
 
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
@@ -413,347 +414,3 @@ function invalidateManifest(server: ViteDevServer): void {
   // Trigger HMR full reload — route changes are structural
   server.hot.send({ type: 'full-reload' });
 }
-
-/**
- * TIM-830: Walk the route tree and collect every page that exports a
- * `searchParams` definition, then emit a module that statically imports
- * each export and registers it into the shared search-params registry.
- *
- * Keys use the un-interpolated route pattern (e.g. '/products/[id]') so
- * <Link> can look up the definition from the original `href` prop before
- * segmentParams are interpolated.
- */
-/** Schema file extensions to check, in priority order. */
-const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
-
-/**
- * TIM-931: Generate the virtual:timber-schema module.
- *
- * When app/schema.{ts,tsx,js,jsx} exists, generates a module that
- * imports the schema and resolves its segmentParams codecs into a
- * bare-name codec map for runtime coercion.
- *
- * When no schema exists, exports null.
- */
-function generateSchemaModule(appDir: string): string {
-  let schemaPath: string | null = null;
-  for (const ext of SCHEMA_EXTENSIONS) {
-    const candidate = join(appDir, `schema${ext}`);
-    if (existsSync(candidate)) {
-      schemaPath = candidate;
-      break;
-    }
-  }
-
-  if (!schemaPath) {
-    return [
-      '// Auto-generated schema loader — no app/schema.ts found.',
-      'export default null;',
-    ].join('\n');
-  }
-
-  return [
-    '// Auto-generated schema loader — do not edit.',
-    '// Generated by timber-routing plugin (TIM-931).',
-    '',
-    `import schema from ${JSON.stringify(schemaPath)};`,
-    `import { resolveSchemaCodecs } from '@timber-js/app/params';`,
-    '',
-    'const globalCodecs = schema?.segmentParams',
-    '  ? resolveSchemaCodecs(schema.segmentParams)',
-    '  : null;',
-    '',
-    'export default globalCodecs;',
-  ].join('\n');
-}
-
-function generateSearchParamsRegistryModule(tree: RouteTree): string {
-  const entries: Array<{ urlPath: string; filePath: string }> = [];
-
-  function walk(node: SegmentNode): void {
-    // params.ts is the canonical location for `export const searchParams`;
-    // page.tsx is the legacy fallback (see codegen.ts `collectRoutes`).
-    if (node.page) {
-      if (node.params && fileHasSearchParamsExport(node.params.filePath)) {
-        entries.push({ urlPath: node.urlPath, filePath: node.params.filePath });
-      } else if (fileHasSearchParamsExport(node.page.filePath)) {
-        entries.push({ urlPath: node.urlPath, filePath: node.page.filePath });
-      }
-    }
-    for (const child of node.children) walk(child);
-    for (const slot of Object.values(node.slots)) walk(slot);
-  }
-  walk(tree.root);
-
-  // Deterministic order for stable output / snapshots
-  entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
-
-  const lines: string[] = [];
-  lines.push('// Auto-generated search-params registry — do not edit.');
-  lines.push('// Generated by timber-routing plugin (TIM-830).');
-  lines.push('');
-  lines.push("import { registerSearchParams } from '@timber-js/app/search-params';");
-  lines.push('');
-
-  // Static imports — Vite/Rolldown tree-shakes the page component body out
-  // of this chunk, leaving only the `searchParams` named export.
-  entries.forEach((entry, i) => {
-    lines.push(`import { searchParams as r${i} } from ${JSON.stringify(entry.filePath)};`);
-  });
-  lines.push('');
-
-  entries.forEach((entry, i) => {
-    lines.push(`registerSearchParams(${JSON.stringify(entry.urlPath)}, r${i});`);
-  });
-  lines.push('');
-
-  // Exporting an empty object keeps the module a real ESM module even
-  // when there are zero entries (no top-level imports in that case).
-  lines.push('export {};');
-  lines.push('');
-
-  return lines.join('\n');
-}
-
-/**
- * Lightweight check for a `searchParams` named export. Mirrors
- * `fileHasExport('searchParams')` in routing/codegen.ts so we stay
- * in sync with what the type codegen detects.
- */
-function fileHasSearchParamsExport(filePath: string): boolean {
-  try {
-    if (!existsSync(filePath)) return false;
-    const content = readFileSync(filePath, 'utf-8');
-    return (
-      /export\s+(const|let|var)\s+searchParams\b/.test(content) ||
-      /export\s*\{[^}]*\bsearchParams\b[^}]*\}/.test(content)
-    );
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Generate the virtual module source code for the route manifest.
- *
- * The output is a default-exported object containing the serialized route tree.
- * All file references use absolute paths (required for virtual modules).
- */
-function generateManifestModule(tree: RouteTree, viteRoot: string): string {
-  const imports: string[] = [];
-  let importIndex = 0;
-
-  /**
-   * Create a lazy import expression for a route file.
-   * Returns the import variable name.
-   */
-  function addImport(file: RouteFile): string {
-    const varName = `_route${importIndex++}`;
-    imports.push(`const ${varName} = () => import("${file.filePath}");`);
-    return varName;
-  }
-
-  /**
-   * Serialize a segment node to a JS object literal.
-   */
-  function serializeNode(node: SegmentNode, indent: string): string {
-    const nextIndent = indent + '  ';
-    const parts: string[] = [];
-
-    parts.push(`${nextIndent}segmentName: ${JSON.stringify(node.segmentName)},`);
-    parts.push(`${nextIndent}segmentType: ${JSON.stringify(node.segmentType)},`);
-    parts.push(`${nextIndent}urlPath: ${JSON.stringify(node.urlPath)},`);
-
-    if (node.paramName) {
-      parts.push(`${nextIndent}paramName: ${JSON.stringify(node.paramName)},`);
-    }
-
-    if (node.interceptionMarker) {
-      parts.push(`${nextIndent}interceptionMarker: ${JSON.stringify(node.interceptionMarker)},`);
-    }
-    if (node.interceptedSegmentName) {
-      parts.push(
-        `${nextIndent}interceptedSegmentName: ${JSON.stringify(node.interceptedSegmentName)},`
-      );
-    }
-
-    // File conventions — absolute paths as lazy imports
-    if (node.page) {
-      const v = addImport(node.page);
-      parts.push(
-        `${nextIndent}page: { load: ${v}, filePath: ${JSON.stringify(node.page.filePath)} },`
-      );
-    }
-    if (node.layout) {
-      const v = addImport(node.layout);
-      parts.push(
-        `${nextIndent}layout: { load: ${v}, filePath: ${JSON.stringify(node.layout.filePath)} },`
-      );
-    }
-    if (node.middleware) {
-      const v = addImport(node.middleware);
-      parts.push(
-        `${nextIndent}middleware: { load: ${v}, filePath: ${JSON.stringify(node.middleware.filePath)} },`
-      );
-    }
-    if (node.access) {
-      const v = addImport(node.access);
-      parts.push(
-        `${nextIndent}access: { load: ${v}, filePath: ${JSON.stringify(node.access.filePath)} },`
-      );
-    }
-    if (node.route) {
-      const v = addImport(node.route);
-      parts.push(
-        `${nextIndent}route: { load: ${v}, filePath: ${JSON.stringify(node.route.filePath)} },`
-      );
-    }
-    if (node.error) {
-      const v = addImport(node.error);
-      parts.push(
-        `${nextIndent}error: { load: ${v}, filePath: ${JSON.stringify(node.error.filePath)} },`
-      );
-    }
-    if (node.default) {
-      const v = addImport(node.default);
-      parts.push(
-        `${nextIndent}default: { load: ${v}, filePath: ${JSON.stringify(node.default.filePath)} },`
-      );
-    }
-    if (node.denied) {
-      const v = addImport(node.denied);
-      parts.push(
-        `${nextIndent}denied: { load: ${v}, filePath: ${JSON.stringify(node.denied.filePath)} },`
-      );
-    }
-    if (node.params) {
-      const v = addImport(node.params);
-      parts.push(
-        `${nextIndent}params: { load: ${v}, filePath: ${JSON.stringify(node.params.filePath)} },`
-      );
-    }
-    // searchParams is now a named export from page.tsx, not a separate file.
-    // The page module's searchParams export is loaded via the page's lazy import.
-    // Runtime registration happens in the route loader using the page module.
-
-    // Status-code files
-    if (node.statusFiles && Object.keys(node.statusFiles).length > 0) {
-      const statusEntries: string[] = [];
-      for (const [code, file] of Object.entries(node.statusFiles)) {
-        const v = addImport(file);
-        statusEntries.push(
-          `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
-        );
-      }
-      parts.push(`${nextIndent}statusFiles: {\n${statusEntries.join(',\n')}\n${nextIndent}},`);
-    }
-
-    // JSON status-code files
-    if (node.jsonStatusFiles && Object.keys(node.jsonStatusFiles).length > 0) {
-      const jsonEntries: string[] = [];
-      for (const [code, file] of Object.entries(node.jsonStatusFiles)) {
-        const v = addImport(file);
-        jsonEntries.push(
-          `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
-        );
-      }
-      parts.push(`${nextIndent}jsonStatusFiles: {\n${jsonEntries.join(',\n')}\n${nextIndent}},`);
-    }
-
-    // Legacy status files
-    if (node.legacyStatusFiles && Object.keys(node.legacyStatusFiles).length > 0) {
-      const legacyEntries: string[] = [];
-      for (const [name, file] of Object.entries(node.legacyStatusFiles)) {
-        const v = addImport(file);
-        legacyEntries.push(
-          `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
-        );
-      }
-      parts.push(
-        `${nextIndent}legacyStatusFiles: {\n${legacyEntries.join(',\n')}\n${nextIndent}},`
-      );
-    }
-
-    // Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.)
-    if (node.metadataRoutes && Object.keys(node.metadataRoutes).length > 0) {
-      const metaEntries: string[] = [];
-      for (const [name, file] of Object.entries(node.metadataRoutes)) {
-        const v = addImport(file);
-        metaEntries.push(
-          `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
-        );
-      }
-      parts.push(`${nextIndent}metadataRoutes: {\n${metaEntries.join(',\n')}\n${nextIndent}},`);
-    }
-
-    // Children
-    if (node.children.length > 0) {
-      const childNodes = node.children.map((c) => serializeNode(c, nextIndent));
-      parts.push(`${nextIndent}children: [\n${childNodes.join(',\n')}\n${nextIndent}],`);
-    } else {
-      parts.push(`${nextIndent}children: [],`);
-    }
-
-    // Parallel slots
-    const slotKeys = Object.keys(node.slots);
-    if (slotKeys.length > 0) {
-      const slotEntries: string[] = [];
-      for (const slotName of slotKeys) {
-        const slotNode = node.slots[slotName]!;
-        slotEntries.push(
-          `${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + '  ')}`
-        );
-      }
-      parts.push(`${nextIndent}slots: {\n${slotEntries.join(',\n')}\n${nextIndent}},`);
-    } else {
-      parts.push(`${nextIndent}slots: {},`);
-    }
-
-    return `${indent}{\n${parts.join('\n')}\n${indent}}`;
-  }
-
-  const rootSerialized = serializeNode(tree.root, '  ');
-
-  // Proxy file
-  let proxyLine = '';
-  if (tree.proxy) {
-    const v = addImport(tree.proxy);
-    proxyLine = `  proxy: { load: ${v}, filePath: ${JSON.stringify(tree.proxy.filePath)} },`;
-  }
-
-  // Global error page (Tier 2)
-  let globalErrorLine = '';
-  if (tree.globalError) {
-    const v = addImport(tree.globalError);
-    globalErrorLine = `  globalError: { load: ${v}, filePath: ${JSON.stringify(tree.globalError.filePath)} },`;
-  }
-
-  // Interception rewrites — computed at build time from the route tree.
-  // Only interceptedPattern and interceptingPrefix are needed at runtime.
-  const rewrites = collectInterceptionRewrites(tree.root);
-  const rewritesLine =
-    rewrites.length > 0
-      ? `  interceptionRewrites: ${JSON.stringify(rewrites.map((r) => ({ interceptedPattern: r.interceptedPattern, interceptingPrefix: r.interceptingPrefix })))},`
-      : '';
-
-  const code = [
-    '// Auto-generated route manifest — do not edit.',
-    '// Generated by timber-routing plugin.',
-    '',
-    ...imports,
-    '',
-    'const manifest = {',
-    `  viteRoot: ${JSON.stringify(viteRoot)},`,
-    proxyLine,
-    globalErrorLine,
-    rewritesLine,
-    `  root: ${rootSerialized},`,
-    '};',
-    '',
-    'export default manifest;',
-  ]
-    .filter((line) => line !== undefined && line !== '')
-    .join('\n');
-
-  return code;
-}

package/src/plugins/server-bundle.ts

@@ -38,6 +38,7 @@ const NODE_BUILTINS: string[] = builtinModules.flatMap((m) => [m, `node:${m}`]);
 // Mirrored on both rsc and ssr environments. See TIM-988.
 const BUILD_ONLY_EXTERNALS: string[] = [
   ...NODE_BUILTINS,
+  'vite',
   'nitro',
   'rollup',
   '@mdx-js/rollup',

package/src/routing/codegen.ts

@@ -8,7 +8,7 @@
  * No runtime overhead — purely static type generation.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import type { RouteTree, SegmentNode } from './types.js';
 import type { ParamEntry, RouteEntry } from './codegen-types.js';
@@ -18,6 +18,7 @@ import {
   emitResolveSegmentFieldHelper,
   formatSearchParamsType,
 } from './codegen-shared.js';
+import { readFileCached } from './file-cache.js';
 import { formatLinkCatchAllOverloads, formatTypedLinkOverloads } from './link-codegen.js';
 
 /** Options for route map generation. */
@@ -257,7 +258,7 @@ function paramTypeForSegment(segmentType: string): ParamEntry['type'] {
 function fileHasExport(filePath: string, exportName: string): boolean {
   if (!existsSync(filePath)) return false;
   try {
-    const content = readFileSync(filePath, 'utf-8');
+    const content = readFileCached(filePath);
     const e = exportName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     return (
       new RegExp(`export\\s+(const|let|var)\\s+${e}\\b`).test(content) ||

package/src/routing/convention-lint.ts

@@ -11,9 +11,10 @@
  * Design doc: 07-routing.md, 10-error-handling.md
  */
 
-import { readFileSync, existsSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import type { RouteTree, SegmentNode } from './types.js';
 import { swallow } from '../server/logger.js';
+import { readFileCached } from './file-cache.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -141,7 +142,7 @@ function checkRouteExports(node: SegmentNode, warnings: ConventionWarning[]): vo
   if (node.route) {
     const filePath = node.route.filePath;
     try {
-      const source = readFileSync(filePath, 'utf-8');
+      const source = readFileCached(filePath);
       if (!EXPORT_PATTERN.test(source)) {
         // Check if there's a default export (common mistake)
         const hasDefaultExport = /export\s+default\b/.test(source);
@@ -265,7 +266,7 @@ function checkFileDefaultExport(
   warnings: ConventionWarning[]
 ): void {
   try {
-    const source = readFileSync(filePath, 'utf-8');
+    const source = readFileCached(filePath);
     if (!DEFAULT_EXPORT_PATTERN.test(source)) {
       warnings.push({
         id: `NO_DEFAULT_EXPORT:${filePath}`,

package/src/routing/file-cache.ts

@@ -0,0 +1,23 @@
+import { readFileSync, statSync } from 'node:fs';
+
+const cache = new Map<string, { mtimeMs: number; size: number; content: string }>();
+
+/**
+ * Read a file's text content, returning a cached copy when the file
+ * hasn't been modified since the last read (checked via mtime + size).
+ *
+ * Falls back to a fresh read on any stat/read error.
+ */
+export function readFileCached(filePath: string): string {
+  try {
+    const stat = statSync(filePath);
+    const entry = cache.get(filePath);
+    if (entry && entry.mtimeMs === stat.mtimeMs && entry.size === stat.size) return entry.content;
+    const content = readFileSync(filePath, 'utf-8');
+    cache.set(filePath, { mtimeMs: stat.mtimeMs, size: stat.size, content });
+    return content;
+  } catch {
+    cache.delete(filePath);
+    return readFileSync(filePath, 'utf-8');
+  }
+}

package/src/routing/interception.ts

@@ -32,11 +32,6 @@ export interface InterceptionRewrite {
    * E.g., "/feed" for a (.)photo/[id] inside /feed/@modal/.
    */
   interceptingPrefix: string;
-  /**
-   * Segments chain from root → intercepting leaf. Used to build the element
-   * tree when the interception is active.
-   */
-  segmentPath: SegmentNode[];
 }
 
 /**
@@ -94,13 +89,7 @@ function collectFromInterceptingNode(
     interceptedBase === '/' ? `/${segmentName}` : `${interceptedBase}/${segmentName}`;
 
   // Find all leaf pages in the intercepting sub-tree
-  collectLeavesWithRewrites(
-    interceptingNode,
-    interceptedUrlBase,
-    parentUrlPath,
-    [...ancestors, interceptingNode],
-    rewrites
-  );
+  collectLeavesWithRewrites(interceptingNode, interceptedUrlBase, parentUrlPath, rewrites);
 }
 
 /**
@@ -111,14 +100,12 @@ function collectLeavesWithRewrites(
   node: SegmentNode,
   interceptedUrlPath: string,
   interceptingPrefix: string,
-  segmentPath: SegmentNode[],
   rewrites: InterceptionRewrite[]
 ): void {
   if (node.page) {
     rewrites.push({
       interceptedPattern: interceptedUrlPath,
       interceptingPrefix,
-      segmentPath: [...segmentPath],
     });
   }
 
@@ -127,13 +114,7 @@ function collectLeavesWithRewrites(
       child.segmentType === 'group'
         ? interceptedUrlPath
         : `${interceptedUrlPath}/${child.segmentName}`;
-    collectLeavesWithRewrites(
-      child,
-      childUrl,
-      interceptingPrefix,
-      [...segmentPath, child],
-      rewrites
-    );
+    collectLeavesWithRewrites(child, childUrl, interceptingPrefix, rewrites);
   }
 }