@paramour-js/next 0.1.0

package/dist/with-typed-routes.js

@@ -0,0 +1,200 @@
+import { resolve } from "node:path";
+import { RouteCollisionError } from "./collisions.js";
+import { diffGenerated, formatRouteDiff, generate, } from "./generate.js";
+import { acquireWatcherLock, watcherLockPath, } from "./lock.js";
+import { DEFAULT_PAGE_EXTENSIONS } from "./scan-app.js";
+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.
+ */
+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.
+ */
+const devWatcherTeardowns = new Map();
+/** Messages already logged — "log once" (TR5) across repeat evaluations. */
+const warnedOnce = new Set();
+/** @internal Test seam: the number of live dev-watcher singletons. */
+export function devWatcherCountForTests() {
+    return devWatcherTeardowns.size;
+}
+/**
+ * @internal Test seam: close every dev watcher, release the pidfile locks,
+ * and clear the log-once state. Also required between tests on Windows —
+ * an open watch handle blocks temp-dir removal.
+ */
+export function resetDevWatchersForTests() {
+    for (const teardown of devWatcherTeardowns.values())
+        teardown();
+    devWatcherTeardowns.clear();
+    warnedOnce.clear();
+}
+/**
+ * Wrap a Next config with route-registry generation (TR4). 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).
+ * - 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).
+ */
+export function withTypedRoutes(config, options = {}) {
+    return async (phase, ctx) => {
+        const resolved = typeof config === "function" ? await config(phase, ctx) : config;
+        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.
+        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).
+        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.
+            warnOnce(`paramour: no route directory (app/, pages/, src/app/, or src/pages/) under ${projectRoot}; route generation skipped`);
+            return resolved;
+        }
+        if (phase === PHASE_PRODUCTION_BUILD) {
+            generateForBuild(dirs, pageExtensions, artifactPath, options.strict ?? false);
+            return resolved;
+        }
+        generateSafely(dirs, pageExtensions, artifactPath);
+        startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath);
+        return resolved;
+    };
+}
+/**
+ * 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).
+ */
+function generateForBuild(dirs, pageExtensions, artifactPath, strict) {
+    let result;
+    try {
+        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
+        // 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.
+        console.warn("paramour: route generation failed; building with stale route types", error);
+        return;
+    }
+    if (!result.written)
+        return;
+    const drift = diffGenerated(result);
+    const message = [
+        result.previousContent === null
+            ? `paramour: ${artifactPath} was missing and has been generated.`
+            : `paramour: ${artifactPath} was out of date and has been regenerated.`,
+        ...formatRouteDiff(drift.app, drift.pages),
+        "Commit the regenerated file, or run `paramour generate` before building.",
+    ].join("\n");
+    if (strict)
+        throw new Error(message);
+    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).
+ */
+function generateSafely(dirs, pageExtensions, artifactPath) {
+    try {
+        generate({ ...dirs, artifactPath, pageExtensions });
+    }
+    catch (error) {
+        if (error instanceof RouteCollisionError)
+            throw error;
+        console.warn("paramour: route generation failed; dev continues with stale route types", error);
+    }
+}
+/**
+ * Start the dev watcher behind both TR6 guards. Failure at any layer leaves
+ * dev running in stale-types mode — never fatal (TR5).
+ */
+function startDevWatcher(projectRoot, dirs, pageExtensions, artifactPath) {
+    const watchedDirs = [dirs.appDir, dirs.pagesDir].filter((dir) => dir !== undefined);
+    const key = `${watchedDirs.join(" ")} ${artifactPath}`;
+    if (devWatcherTeardowns.has(key))
+        return;
+    let lock;
+    try {
+        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
+        // 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
+        // --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)})`);
+        return;
+    }
+    const watcher = watchRouteDirs(watchedDirs, {
+        ignorePaths: [artifactPath],
+        onError: (error) => {
+            warnOnce("paramour: dev watcher failed; dev continues with stale route types", error);
+        },
+        onRescan: () => {
+            try {
+                generate({ ...dirs, artifactPath, pageExtensions });
+            }
+            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).
+                    console.warn(`paramour: ${error.message}; dev continues with the last good artifact`);
+                    return;
+                }
+                throw error; // routed to onError by the watcher (TR5 non-fatal)
+            }
+        },
+    });
+    // A failed watchRouteDirs returns a no-op handle and is still registered:
+    // retrying on every config re-evaluation would just warn repeatedly.
+    devWatcherTeardowns.set(key, () => {
+        watcher.close();
+        lock.release?.();
+    });
+}
+/** TR5 "log once": repeat evaluations/events don't spam the dev console. */
+function warnOnce(message, detail) {
+    if (warnedOnce.has(message))
+        return;
+    warnedOnce.add(message);
+    if (detail === undefined)
+        console.warn(message);
+    else
+        console.warn(message, detail);
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@paramour-js/next",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./app": {
+      "types": "./dist/app.d.ts",
+      "default": "./dist/app.js"
+    },
+    "./pages": {
+      "types": "./dist/pages.d.ts",
+      "default": "./dist/pages.js"
+    }
+  },
+  "bin": {
+    "paramour": "./bin/paramour.js"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "magicast": "^0.3.5",
+    "tinyglobby": "^0.2.15",
+    "paramour": "0.1.0"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=18.2.0"
+  },
+  "devDependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.0",
+    "happy-dom": "^15.11.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.4.3"
+  },
+  "description": "Next.js integration for paramour: withTypedRoutes, App and Pages Router hooks, PageProps glue, and the codegen CLI.",
+  "author": "Jason Paff <jasonpaff@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JasonPaff/paramour.git",
+    "directory": "packages/next"
+  },
+  "homepage": "https://github.com/JasonPaff/paramour#readme",
+  "bugs": {
+    "url": "https://github.com/JasonPaff/paramour/issues"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}