@paramour-js/next 0.3.1 → 0.4.1

package/dist/with-typed-routes.js

@@ -7,18 +7,18 @@ import { resolveRouteDirs } from "./scan.js";
 import { watchRouteDirs } from "./watch.js";
 /**
  * Phase constants from `next/constants`, hardcoded so the package stays
- * hermetic (TR4 hermeticity ruling): the values are stable, documented
- * public API, and importing them would make `next` a runtime dependency.
+ * hermetic: the values are stable, documented public API, and importing them
+ * would make `next` a runtime dependency.
  */
 const PHASE_DEVELOPMENT_SERVER = "phase-development-server";
 const PHASE_PRODUCTION_BUILD = "phase-production-build";
 /**
- * TR6 guard 1 — the in-process singleton, keyed by route dirs + artifact
- * path. Load-bearing even for a single `next dev`: the spike-#1 census found
- * Turbopack dev invokes the config function twice in the same process.
+ * The in-process single-writer guard — a singleton keyed by route dirs +
+ * artifact path. Load-bearing even for a single `next dev`: Turbopack dev
+ * invokes the config function twice in the same process.
  */
 const devWatcherTeardowns = new Map();
-/** Messages already logged — "log once" (TR5) across repeat evaluations. */
+/** Messages already logged — "log once" across repeat evaluations. */
 const warnedOnce = new Set();
 /** @internal Test seam: the number of live dev-watcher singletons. */
 export function devWatcherCountForTests() {
@@ -36,21 +36,22 @@ export function resetDevWatchersForTests() {
     warnedOnce.clear();
 }
 /**
- * Wrap a Next config with route-registry generation (TR4). Returns the
+ * Wrap a Next config with route-registry generation. Returns the
  * config-function form; Next's phase argument is the mode discriminator:
  *
  * - production build → one generation pass before the config is returned
  *   (the build type-checks against fresh routes); drift warns loudly, or
  *   fails the build under `strict: true`.
  * - dev server → one immediate generation pass, then the debounced watcher
- *   (TR5) behind both single-writer guards (TR6).
+ *   behind both single-writer guards (the in-process singleton and the
+ *   cross-process pidfile lock).
  * - every other phase → pass-through, no generation.
  *
  * Two states throw during config evaluation instead of degrading to
  * stale-types mode, both phases alike, because Next itself has no valid
- * build for them: an app↔pages route collision (PR9), and discovery's
- * populated-ignored-dir config error (spike-2 ruling — Next is silently
- * serving none of those pages).
+ * build for them: an app↔pages route collision, and discovery's
+ * populated-ignored-dir config error (Next is silently serving none of those
+ * pages).
  */
 export function withTypedRoutes(config, options = {}) {
     return async (phase, ctx) => {
@@ -58,16 +59,17 @@ export function withTypedRoutes(config, options = {}) {
         if (phase !== PHASE_DEVELOPMENT_SERVER && phase !== PHASE_PRODUCTION_BUILD)
             return resolved;
         // The dev server and every build worker evaluate the config with the
-        // project root as cwd (spike-#1 census); TR7's CLI flags are the home
-        // for anything more configurable than this.
+        // project root as cwd; the CLI flags are the home for anything more
+        // configurable than this.
         const projectRoot = process.cwd();
         const artifactPath = resolve(projectRoot, options.outFile ?? "paramour-env.d.ts");
         const pageExtensions = resolved.pageExtensions ?? DEFAULT_PAGE_EXTENSIONS;
-        // May throw the spike-2 config error — deliberately not caught (above).
+        // May throw the populated-ignored-dir config error — deliberately not
+        // caught (see above).
         const dirs = resolveRouteDirs(projectRoot, pageExtensions);
         if (dirs.appDir === undefined && dirs.pagesDir === undefined) {
-            // §7.3: codegen is never load-bearing — a config wrapper must not
-            // take down `next dev`/`next build` over a missing route dir.
+            // Codegen is never load-bearing — a config wrapper must not take down
+            // `next dev`/`next build` over a missing route dir.
             warnOnce(`paramour: no route directory (app/, pages/, src/app/, or src/pages/) under ${projectRoot}; route generation skipped`);
             return resolved;
         }
@@ -81,12 +83,12 @@ export function withTypedRoutes(config, options = {}) {
     };
 }
 /**
- * Build-phase pass (TR4): regenerate, then warn loudly on drift — naming the
- * paths that appeared/disappeared and the router they moved in — but
- * continue; `strict` upgrades drift to a thrown error *after* the file is
- * already corrected. A missing artifact counts as drift: that is exactly the
- * CI-degrades-to-world-A scenario the committed file exists to prevent
- * (TR3). A route collision is NOT incidental failure and rethrows (PR9).
+ * Build-phase pass: regenerate, then warn loudly on drift — naming the paths
+ * that appeared/disappeared and the router they moved in — but continue;
+ * `strict` upgrades drift to a thrown error *after* the file is already
+ * corrected. A missing artifact counts as drift: that is exactly the
+ * CI-degrades-to-world-A scenario the committed file exists to prevent. A
+ * route collision is NOT incidental failure and rethrows.
  */
 function generateForBuild(dirs, pageExtensions, artifactPath, strict) {
     let result;
@@ -94,13 +96,13 @@ function generateForBuild(dirs, pageExtensions, artifactPath, strict) {
         result = generate({ ...dirs, artifactPath, pageExtensions });
     }
     catch (error) {
-        // PR9: Next fails this build anyway; surfacing the collision from the
-        // config evaluation names the actual problem instead of leaving a stale
+        // Next fails this build anyway; surfacing the collision from the config
+        // evaluation names the actual problem instead of leaving a stale
         // artifact to confuse the type errors that follow.
         if (error instanceof RouteCollisionError)
             throw error;
-        // §7.3 again: incidental generation failure is stale types, not a
-        // broken build. Only *drift* is allowed to fail a strict build.
+        // Again: incidental generation failure is stale types, not a broken
+        // build. Only *drift* is allowed to fail a strict build.
         console.warn("paramour: route generation failed; building with stale route types", error);
         return;
     }
@@ -119,9 +121,10 @@ function generateForBuild(dirs, pageExtensions, artifactPath, strict) {
     console.warn(message);
 }
 /**
- * Dev-phase generation (TR4): failure warns and continues (§7.3) — except a
- * route collision, which throws from the config evaluation here exactly as
- * in the build phase (PR9; only the running WATCHER treats it non-fatally).
+ * Dev-phase generation: failure warns and continues (codegen is never
+ * load-bearing) — except a route collision, which throws from the config
+ * evaluation here exactly as in the build phase; only the running WATCHER
+ * treats it non-fatally.
  */
 function generateSafely(dirs, pageExtensions, artifactPath) {
     try {
@@ -134,8 +137,8 @@ function generateSafely(dirs, pageExtensions, artifactPath) {
     }
 }
 /**
- * Start the dev watcher behind both TR6 guards. Failure at any layer leaves
- * dev running in stale-types mode — never fatal (TR5).
+ * Start the dev watcher behind both single-writer guards. Failure at any
+ * layer leaves dev running in stale-types mode — never fatal.
  */
 function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
     const watchedDirs = [dirs.appDir, dirs.pagesDir].filter((dir) => dir !== undefined);
@@ -147,14 +150,14 @@ function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
         lock = acquireWatcherLock(watcherLockPath(projectRoot));
     }
     catch (error) {
-        // §7.3: a corrupt lock location (e.g. a directory at the pidfile path)
-        // must not take down `next dev` — stale-types mode, like every other
+        // A corrupt lock location (e.g. a directory at the pidfile path) must
+        // not take down `next dev` — stale-types mode, like every other
         // watcher-layer failure.
         warnOnce("paramour: dev watcher failed; dev continues with stale route types", error);
         return;
     }
     if (!lock.acquired) {
-        // TR6: another live process owns the watcher (e.g. `paramour generate
+        // Another live process owns the watcher (e.g. `paramour generate
         // --watch` beside `next dev`). Initial generation above already ran, so
         // dev is still correct from second zero.
         console.warn(`paramour: watcher already running (pid ${String(lock.ownerPid)})`);
@@ -171,13 +174,13 @@ function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
             }
             catch (error) {
                 if (error instanceof RouteCollisionError) {
-                    // PR9's watch exception: a mid-watch collision is usually a file
-                    // mid-move — log loudly every time (not once: it stays broken
-                    // until fixed), keep the last good artifact, keep running (TR5).
+                    // The collision watch exception: a mid-watch collision is usually
+                    // a file mid-move — log loudly every time (not once: it stays
+                    // broken until fixed), keep the last good artifact, keep running.
                     console.warn(`paramour: ${error.message}; dev continues with the last good artifact`);
                     return;
                 }
-                throw error; // routed to onError by the watcher (TR5 non-fatal)
+                throw error; // routed to onError by the watcher — non-fatal
             }
         },
     });
@@ -188,7 +191,7 @@ function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
         lock.release?.();
     });
 }
-/** TR5 "log once": repeat evaluations/events don't spam the dev console. */
+/** "Log once": repeat evaluations/events don't spam the dev console. */
 function warnOnce(message, detail) {
     if (warnedOnce.has(message))
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "type": "module",
   "exports": {
     ".": {
@@ -17,6 +17,10 @@
     "./pages": {
       "types": "./dist/pages.d.ts",
       "default": "./dist/pages.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "sideEffects": false,
@@ -30,7 +34,7 @@
     "jiti": "^2.7.0",
     "magicast": "^0.3.5",
     "tinyglobby": "^0.2.15",
-    "paramour": "0.5.1"
+    "paramour": "0.6.0"
   },
   "peerDependencies": {
     "next": ">=15",