@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/plugins/routing.ts

@@ -9,21 +9,12 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { scanRoutes } from '../routing/scanner.js';
-import { generateRouteMap } from '../routing/codegen.js';
-import {
-  buildDirToRouteMap,
-  writeSegmentTypes,
-  type SegmentInfo,
-} from '../routing/segment-codegen.js';
+import { buildDirToRouteMap, type SegmentInfo } from '../routing/segment-codegen.js';
+import { writeRouteCodegen, flushCodegenWrites } from '../routing/codegen-write.js';
 import { validateSchemaAgainstRoutes } from '../routing/schema-validation.js';
-import {
-  generateManifestModule,
-  generateSearchParamsRegistryModule,
-  generateSchemaModule,
-} from '../routing/manifest-codegen.js';
+import { generateManifestModule, generateSchemaModule } from '../routing/manifest-codegen.js';
 import {
   lintConventions,
   checkAppDirExists,
@@ -34,21 +25,6 @@ import type { PluginContext } from '../plugin-context.js';
 const VIRTUAL_MODULE_ID = 'virtual:timber-route-manifest';
 const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_MODULE_ID}`;
 
-// TIM-830: Search-params registry virtual module.
-//
-// Statically imports the `searchParams` named export from every page
-// that exports one, and registers each definition into the shared
-// search-params registry keyed by the un-interpolated route pattern
-// (e.g. '/products/[id]'). This lets `<Link>` serialize flat
-// `Partial<T>` values at runtime without callers importing the
-// definition at the call site.
-//
-// The imports are STATIC (`import { searchParams as r0 } from '...'`)
-// so Vite/Rolldown tree-shakes each page's component body out of the
-// registry chunk — only the `searchParams` named export is pulled in.
-const SEARCH_PARAMS_REGISTRY_ID = 'virtual:timber-search-params-registry';
-const RESOLVED_SEARCH_PARAMS_REGISTRY_ID = `\0${SEARCH_PARAMS_REGISTRY_ID}`;
-
 // TIM-931: Schema virtual module.
 //
 // When app/schema.ts exists, this module imports it and resolves the
@@ -69,68 +45,26 @@ const SEGMENT_PREFIX = '\0$segment:';
  * File convention names we track for changes that require manifest regeneration.
  */
 const ROUTE_FILE_PATTERNS =
-  /\/(page|layout|middleware|access|route|error|global-error|default|denied|params|schema|\d{3}|[45]xx|sitemap|robots|manifest|favicon|icon|opengraph-image|apple-icon)\./;
+  /\/(page|layout|middleware|access|route|error|global-error|default|denied|schema|\d{3}|[45]xx|sitemap|robots|manifest|favicon|icon|opengraph-image|apple-icon)\./;
 
 /**
  * Create the timber-routing Vite plugin.
  *
  * Hooks: resolveId, load, buildStart, configureServer
  */
-/** Absolute path to the generated route map declaration file. */
-const CODEGEN_OUTPUT = '.timber/timber-routes.d.ts';
-
-/**
- * Content of the timber-env.d.ts file written to the project root.
- *
- * Uses a triple-slash reference so TypeScript auto-discovers the generated
- * route map without the user needing to edit tsconfig.json — same pattern
- * as Next.js's next-env.d.ts.
- *
- * Also references `vite/client` so side-effect imports like
- * `import './globals.css'` type-check without ts(2882), and so
- * `import.meta.env`, `import.meta.hot`, `import.meta.glob`, asset
- * imports (`*.png`, `*.svg`, …), CSS modules, and `?url`/`?raw`/
- * `?inline` query variants all resolve without the user editing
- * tsconfig.json themselves. Next.js's next-env.d.ts plays the same
- * role via `next/types/global`.
- *
- * `vite` is a peer dep of `@timber-js/app`, so the reference always
- * resolves in a correctly-installed project.
- */
-const TIMBER_ENV_DTS = [
-  '// This file is auto-generated by timber.js. Do not edit.',
-  '// It ensures TypeScript picks up the generated route types and',
-  '// Vite-provided ambient types (CSS, assets, import.meta.env, HMR).',
-  '/* eslint-disable @typescript-eslint/triple-slash-reference */',
-  '/// <reference path=".timber/timber-routes.d.ts" />',
-  '/// <reference types="vite/client" />',
-  '',
-].join('\n');
-
 /**
  * Write the generated route map and the timber-env.d.ts reference file.
  *
- * Fire-and-forget — never awaited to avoid blocking the hot path.
- * Errors are swallowed; a missing .d.ts is a developer UX issue, not a runtime failure.
+ * Not awaited, to avoid blocking the hot path — use `flushCodegenWrites()` to
+ * wait for the writes to land. Failures are logged, not thrown: a missing .d.ts
+ * is a developer UX issue in dev/build, not a runtime failure. (`timber check`
+ * calls `writeRouteCodegen` directly and does treat a failure as fatal.)
  */
 function writeCodegen(ctx: PluginContext): void {
   if (!ctx.routeTree) return;
-  const timberDir = join(ctx.root, '.timber');
-  const content = generateRouteMap(ctx.routeTree, { appDir: ctx.appDir, outputDir: timberDir });
-  const routesPath = join(ctx.root, CODEGEN_OUTPUT);
-  const envPath = join(ctx.root, 'timber-env.d.ts');
-  mkdir(timberDir, { recursive: true })
-    .then(() =>
-      Promise.all([
-        writeFile(routesPath, content, 'utf-8'),
-        writeFile(envPath, TIMBER_ENV_DTS, 'utf-8'),
-        writeSegmentTypes(ctx.routeTree!, ctx.appDir, ctx.root),
-      ])
-    )
-    .catch((err) => {
-      // Non-fatal — types are a dev convenience, but log so issues are visible
-      console.warn('[timber] Failed to write codegen output:', err);
-    });
+  void writeRouteCodegen(ctx.routeTree, ctx.appDir, ctx.root).catch((err) => {
+    console.warn('[timber] Failed to write codegen output:', err);
+  });
 }
 
 export function timberRouting(ctx: PluginContext): Plugin {
@@ -160,10 +94,26 @@ export function timberRouting(ctx: PluginContext): Plugin {
     }
 
     ctx.timer.start('route-scan');
-    ctx.routeTree = scanRoutes(ctx.appDir, {
+    const tree = scanRoutes(ctx.appDir, {
       pageExtensions: ctx.config.pageExtensions,
     });
     ctx.timer.end('route-scan');
+
+    // Lint conventions (empty app, missing methods, missing root layout).
+    // Runs on the scanned tree *before* it is published: error-level findings
+    // are proven-fatal misconfigurations — the app cannot render at all — so
+    // the tree must not reach codegen, the manifest, or a live dev server's
+    // module graph. Fail loudly rather than let the developer discover it as
+    // an unattributed React error on an unrelated page (TIM-1329). Never
+    // deduplicated against `warnedFiles`: an error must not be downgraded to
+    // silence by an earlier scan in the same process.
+    const conventionWarnings = lintConventions(tree, ctx.appDir);
+    const fatal = conventionWarnings.filter((w) => w.level === 'error');
+    if (fatal.length > 0) {
+      throw new Error(formatConventionWarnings(fatal, { color: false }));
+    }
+
+    ctx.routeTree = tree;
     dirToRoute = buildDirToRouteMap(ctx.routeTree, ctx.appDir);
     writeCodegen(ctx);
 
@@ -172,8 +122,6 @@ export function timberRouting(ctx: PluginContext): Plugin {
     // See design/41-global-params.md §Auto-Scaffolding
     warnSchemaValidation(ctx);
 
-    // Lint conventions (empty app, missing methods, missing root layout)
-    const conventionWarnings = lintConventions(ctx.routeTree, ctx.appDir);
     const newConventionWarnings = conventionWarnings.filter((w) => !warnedFiles.has(w.id));
     if (newConventionWarnings.length > 0) {
       for (const w of newConventionWarnings) warnedFiles.add(w.id);
@@ -206,14 +154,6 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return RESOLVED_VIRTUAL_ID;
       }
 
-      // TIM-830: Search-params registry virtual module
-      if (
-        cleanId === SEARCH_PARAMS_REGISTRY_ID ||
-        cleanId.endsWith(`/${SEARCH_PARAMS_REGISTRY_ID}`)
-      ) {
-        return RESOLVED_SEARCH_PARAMS_REGISTRY_ID;
-      }
-
       // TIM-931: Schema virtual module
       if (cleanId === SCHEMA_ID || cleanId.endsWith(`/${SCHEMA_ID}`)) {
         return RESOLVED_SCHEMA_ID;
@@ -253,13 +193,6 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return generateManifestModule(ctx.routeTree!, ctx.root);
       }
 
-      if (id === RESOLVED_SEARCH_PARAMS_REGISTRY_ID) {
-        if (!ctx.routeTree) {
-          rescan();
-        }
-        return generateSearchParamsRegistryModule(ctx.routeTree!);
-      }
-
       if (id === RESOLVED_SCHEMA_ID) {
         return generateSchemaModule(ctx.appDir);
       }
@@ -288,6 +221,19 @@ export function timberRouting(ctx: PluginContext): Plugin {
       rescan();
     },
 
+    /**
+     * Wait for the codegen writes started by `buildStart` before the build
+     * reports done.
+     *
+     * `writeCodegen` runs unawaited so route scanning never blocks on disk.
+     * Without this the build can finish — and the CLI can exit — while the
+     * generated `.d.ts` files are still being written, leaving a project root
+     * with no route types after an apparently successful build.
+     */
+    closeBundle() {
+      return flushCodegenWrites();
+    },
+
     /**
      * Set up file watcher in dev mode.
      *
@@ -305,6 +251,59 @@ export function timberRouting(ctx: PluginContext): Plugin {
       /** Snapshot of the last generated manifest, used to detect structural changes. */
       let lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
 
+      /**
+       * Rescan without letting a rejected route tree kill the dev server.
+       *
+       * `rescan()` throws on hard misconfigurations — duplicate conventions,
+       * route collisions, a status file that is not a client component. Those
+       * throws are correct at startup and in `vite build`, but here they run
+       * inside a chokidar listener, where an exception is an unhandled
+       * rejection that takes the process down mid-edit. Report and keep the
+       * last good tree so the server stays up and the fix is one save away.
+       *
+       * Returns false when the scan failed, so callers skip the manifest
+       * regeneration that would otherwise publish a stale tree as fresh.
+       */
+      /**
+       * True while the last rescan is still failing.
+       *
+       * Recovery has to force a reload even when the manifest is byte-identical.
+       * Adding a missing `'use client'` back to a status file changes no route
+       * metadata, so the content-change path would send nothing and leave the
+       * error overlay on screen over a page that is now fine.
+       */
+      let scanFailed = false;
+
+      const rescanSafely = (): boolean => {
+        try {
+          rescan();
+          if (scanFailed) {
+            scanFailed = false;
+            // Force the reload: see `scanFailed`.
+            lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
+            invalidateManifest(devServer);
+          }
+          return true;
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          process.stderr.write(
+            `[timber] Route scan failed — keeping previous routes.\n${message}\n`
+          );
+          scanFailed = true;
+
+          // The terminal is not the only surface that needs this. Keeping the
+          // previous tree keeps the *server* alive, but it does not un-edit the
+          // file: Vite still re-transforms it, so the very next render hits the
+          // failure this scan just diagnosed — and the browser's version of it
+          // names nothing. Put the diagnosis where the developer is looking.
+          devServer.hot.send({
+            type: 'error',
+            err: { message, stack: '', plugin: 'timber-routing' },
+          });
+          return false;
+        }
+      };
+
       /**
        * Handle a route-significant file being added or removed.
        * Always triggers a full-reload since the route tree structure changed.
@@ -313,7 +312,7 @@ export function timberRouting(ctx: PluginContext): Plugin {
         if (!filePath.startsWith(ctx.appDir)) return;
         if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 
-        rescan();
+        if (!rescanSafely()) return;
         lastManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
         invalidateManifest(devServer);
       };
@@ -330,7 +329,7 @@ export function timberRouting(ctx: PluginContext): Plugin {
         if (!filePath.startsWith(ctx.appDir)) return;
         if (!ROUTE_FILE_PATTERNS.test(filePath)) return;
 
-        rescan();
+        if (!rescanSafely()) return;
         const newManifest = ctx.routeTree ? generateManifestModule(ctx.routeTree, ctx.root) : '';
         if (newManifest !== lastManifest) {
           lastManifest = newManifest;
@@ -392,11 +391,7 @@ function invalidateManifest(server: ViteDevServer): void {
     const env = server.environments[envName];
     if (!env?.moduleGraph) continue;
 
-    for (const virtualId of [
-      RESOLVED_VIRTUAL_ID,
-      RESOLVED_SEARCH_PARAMS_REGISTRY_ID,
-      RESOLVED_SCHEMA_ID,
-    ]) {
+    for (const virtualId of [RESOLVED_VIRTUAL_ID, RESOLVED_SCHEMA_ID]) {
       const mod = env.moduleGraph.getModuleById(virtualId);
       if (mod) {
         env.moduleGraph.invalidateModule(mod);

package/src/plugins/shims.ts

@@ -55,7 +55,6 @@ export const SUBPATH_SRC_MAP: Record<string, string> = {
   'cookies': 'cookies/index.ts',
   'params': 'params/index.ts',
   'search-params': 'search-params/index.ts',
-  'segment-params': 'segment-params/index.ts',
 
   'cache/stores/memory': 'cache/stores/memory.ts',
   'cache/stores/redis': 'cache/stores/redis.ts',