@paramour-js/next 0.11.1 → 0.11.3

package/dist/doctor/checks.js

@@ -241,8 +241,7 @@ async function trailingSlashCheck(nextConfigPath, definitions) {
     const setting = `trailingSlash: ${String(configured)}`;
     // The routes come from the app's own paramour, which may predate the
     // option and lack the member: missing reads as the R6 default.
-    const mismatched = definitions.filter((definition) => (definition.route["~trailingSlash"] ?? false) !==
-        configured);
+    const mismatched = definitions.filter((definition) => (definition.route["~trailingSlash"] ?? false) !== configured);
     if (mismatched.length === 0) {
         return {
             label: `trailing slash: route definitions match ${name} (${setting})`,

package/dist/init/wrap-next-config.d.ts

@@ -30,12 +30,13 @@ export declare function findNextConfig(projectRoot: string): FoundNextConfig | u
 export declare function manualSnippet(): string;
 /**
  * Reads `trailingSlash` from a next.config source for `doctor`, statically:
- * the default export (or CJS `module.exports`) is followed through wrapper
- * calls (first argument), TS `as`/`satisfies`, and top-level `const`
- * bindings to an object literal. A literal without the key is Next's default,
- * `false`. Anything else (a config function, a non-literal value, a spread
- * that could carry the key) is `undefined`: doctor stays quiet rather than
- * guess, since evaluating the config would run user code.
+ * the default export (or CJS `module.exports`) is followed through
+ * single-argument wrapper calls, TS `as`/`satisfies`, and top-level bindings
+ * to an object literal. A literal without the key is Next's default, `false`.
+ * Anything else (a config function, a non-literal value, a spread that could
+ * carry the key, a multi-argument call, a binding written after its
+ * declaration) is `undefined`: doctor stays quiet rather than guess, since
+ * evaluating the config would run user code.
  */
 export declare function readTrailingSlash(source: string): Promise<boolean | undefined>;
 /**

package/dist/init/wrap-next-config.js

@@ -1,6 +1,14 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 const IMPORT_LINE = `import { withTypedRoutes } from "@paramour-js/next";`;
+/** {@link writtenBindings}' name for `module.exports` (no identifier has a dot). */
+const MODULE_EXPORTS = "module.exports";
+/** The `Object` statics that write their first argument's properties. */
+const OBJECT_WRITERS = new Set([
+    "assign",
+    "defineProperties",
+    "defineProperty",
+]);
 /**
  * Wrap-state probe for `doctor`: same import/callee detection the codemod
  * uses for idempotence, without mutating anything.
@@ -43,12 +51,13 @@ export function manualSnippet() {
 }
 /**
  * Reads `trailingSlash` from a next.config source for `doctor`, statically:
- * the default export (or CJS `module.exports`) is followed through wrapper
- * calls (first argument), TS `as`/`satisfies`, and top-level `const`
- * bindings to an object literal. A literal without the key is Next's default,
- * `false`. Anything else (a config function, a non-literal value, a spread
- * that could carry the key) is `undefined`: doctor stays quiet rather than
- * guess, since evaluating the config would run user code.
+ * the default export (or CJS `module.exports`) is followed through
+ * single-argument wrapper calls, TS `as`/`satisfies`, and top-level bindings
+ * to an object literal. A literal without the key is Next's default, `false`.
+ * Anything else (a config function, a non-literal value, a spread that could
+ * carry the key, a multi-argument call, a binding written after its
+ * declaration) is `undefined`: doctor stays quiet rather than guess, since
+ * evaluating the config would run user code.
  */
 export async function readTrailingSlash(source) {
     const { parseModule } = await import("magicast");
@@ -59,6 +68,7 @@ export async function readTrailingSlash(source) {
     catch {
         return undefined;
     }
+    const written = writtenBindings(program);
     const body = asNodes(program.body);
     const bindings = new Map();
     let exported;
@@ -66,7 +76,9 @@ export async function readTrailingSlash(source) {
         if (statement.type === "VariableDeclaration") {
             for (const declarator of asNodes(statement.declarations)) {
                 const id = asNode(declarator.id);
-                if (id?.type === "Identifier" && typeof id.name === "string") {
+                if (id?.type === "Identifier" &&
+                    typeof id.name === "string" &&
+                    !written.has(id.name)) {
                     bindings.set(id.name, declarator.init);
                 }
             }
@@ -78,7 +90,7 @@ export async function readTrailingSlash(source) {
             const expression = asNode(statement.expression);
             if (expression?.type === "AssignmentExpression" &&
                 isModuleExports(asNode(expression.left))) {
-                exported = expression.right;
+                exported = written.has(MODULE_EXPORTS) ? undefined : expression.right;
             }
         }
     }
@@ -181,8 +193,13 @@ function trailingSlashOf(value, bindings, depth) {
         return undefined;
     switch (node.type) {
         case "CallExpression": {
-            const [first] = asNodes(node.arguments);
-            return trailingSlashOf(first, bindings, depth + 1);
+            // Only a single-argument wrapper (`withTypedRoutes(config)`, curried
+            // `withX(options)(config)`) is followed. With more arguments nothing
+            // says which one is the config, and plugin options often come first.
+            const [only, ...rest] = asNodes(node.arguments);
+            return rest.length === 0
+                ? trailingSlashOf(only, bindings, depth + 1)
+                : undefined;
         }
         case "Identifier": {
             return typeof node.name === "string" && bindings.has(node.name)
@@ -221,3 +238,86 @@ function trailingSlashOf(value, bindings, depth) {
 function withTypedRoutesLocal(items) {
     return items.find((item) => item.from === "@paramour-js/next" && item.imported === "withTypedRoutes")?.local;
 }
+/**
+ * The binding a write lands on: an identifier, or `module.exports`. TS
+ * wrappers are seen through, so `(config as NextConfig).x = …` counts.
+ */
+function writeTarget(value) {
+    let node = asNode(value);
+    while (node?.type === "ParenthesizedExpression" ||
+        node?.type === "TSAsExpression" ||
+        node?.type === "TSNonNullExpression" ||
+        node?.type === "TSSatisfiesExpression") {
+        node = asNode(node.expression);
+    }
+    if (node?.type === "Identifier" && typeof node.name === "string") {
+        return node.name;
+    }
+    return isModuleExports(node) ? MODULE_EXPORTS : undefined;
+}
+/**
+ * Every binding the program writes after its declaration, which makes its
+ * declared value an unreliable read: a direct property write or delete
+ * (`c.x = …`, `c[k] = …`, `delete c.x`), an `Object.assign` /
+ * `Object.defineProperty` / `Object.defineProperties` target, or a
+ * reassignment (`c = …`, or `module.exports` assigned more than once). A
+ * write to a nested object (`c.experimental.x = …`) is not counted, since it
+ * cannot change `c.trailingSlash`. The whole program is searched, not just
+ * the top level, because a static-export toggle usually sits under an `if`.
+ * Scope is ignored, so a shadowing parameter of the same name also counts;
+ * that errs toward unknown, which only costs a finding.
+ */
+function writtenBindings(program) {
+    const written = new Set();
+    let moduleExportsAssignments = 0;
+    const add = (target) => {
+        if (target !== undefined)
+            written.add(target);
+    };
+    const visit = (node) => {
+        if (node.type === "AssignmentExpression") {
+            const left = asNode(node.left);
+            // `module.exports` is itself a member expression: test it first.
+            if (isModuleExports(left)) {
+                moduleExportsAssignments += 1;
+            }
+            else if (left?.type === "MemberExpression") {
+                add(writeTarget(left.object));
+            }
+            else {
+                add(writeTarget(left));
+            }
+        }
+        else if (node.type === "UnaryExpression" && node.operator === "delete") {
+            const argument = asNode(node.argument);
+            if (argument?.type === "MemberExpression") {
+                add(writeTarget(argument.object));
+            }
+        }
+        else if (node.type === "CallExpression") {
+            const callee = asNode(node.callee);
+            const object = asNode(callee?.object);
+            const property = asNode(callee?.property);
+            if (callee?.type === "MemberExpression" &&
+                callee.computed !== true &&
+                object?.type === "Identifier" &&
+                object.name === "Object" &&
+                property?.type === "Identifier" &&
+                typeof property.name === "string" &&
+                OBJECT_WRITERS.has(property.name)) {
+                add(writeTarget(asNodes(node.arguments)[0]));
+            }
+        }
+        for (const child of Object.values(node)) {
+            for (const item of Array.isArray(child) ? asNodes(child) : [child]) {
+                const next = asNode(item);
+                if (next !== undefined)
+                    visit(next);
+            }
+        }
+    };
+    visit(program);
+    if (moduleExportsAssignments > 1)
+        written.add(MODULE_EXPORTS);
+    return written;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "type": "module",
   "exports": {
     ".": {
@@ -51,7 +51,7 @@
     "react-dom": "^19.2.0",
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
-    "paramour": "0.11.1"
+    "paramour": "0.11.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>",

package/skills/paramour/SKILL.md

@@ -12,7 +12,7 @@ Paramour is a type-safe routing companion for Next.js: each route is defined onc
 1. Import only from package barrels: `paramour`, `@paramour-js/next`, `@paramour-js/next/app`, `@paramour-js/next/pages`, `@paramour-js/next/testing`. Never import `dist/` or deep source paths.
 2. Codec modifier legality is type-state: illegal chains do not compile (the method's type becomes `never`) and throw at runtime for JS callers. The rules:
    - `.optional()` and `.default()` apply only to a bare, unmodified single-value codec — at most ONE of the two, at most once. `.optional().default()`, `.default().optional()`, and any repeat are illegal.
-   - `.catch()` applies at most once and combines with either presence modifier in either order. It recovers parse failures of PRESENT wire values only — never absence. On an `.optional()` codec the fallback may be `undefined`, so a bad value reads as absent (`.optional().catch(undefined)`).
+   - `.catch()` applies at most once and combines with either presence modifier in either order, except that an `undefined` fallback needs `.optional()` first. It recovers parse failures of PRESENT wire values only — never absence. On an `.optional()` codec the fallback may be `undefined`, so a bad value reads as absent (`.optional().catch(undefined)`).
    - `p.array(...)` codecs take no `.optional()`/`.default()` (an absent key and `[]` are the same wire state). `.catch()` is allowed.
    - Codecs in a `params:` config take no presence modifiers at all (`.optional()`/`.default()` are illegal there); `.catch()` is allowed.
    - `p.csv(element)`/`p.array(element)` elements must be bare unmodified scalars: no modifiers, no csv inside csv, no array-arity element.

package/skills/paramour/references/authoring.md

@@ -92,7 +92,7 @@ href(productRoute, { params: { id: 1 }, hash: "reviews" }); // "#reviews" append
 href("/about", { hash: "team" }); // string form: registered STATIC paths only
 ```
 
-`href` returns `Href` — a string subtype accepted by `next/link`, `router.push`, `redirect` unchanged. Required params/search make the options argument required; defaulted/optional/array keys are omittable. Serialization failures (bad value, empty segment, required catch-all given `[]`) throw `SerializeError` at link-build time. A route defined with `trailingSlash: true` (match `next.config`'s `trailingSlash`) builds `/asset/?q=1` instead of `/asset?q=1`; the root stays `/` and the path literal never ends in `/`. Lower-level pieces: `buildPath(route, params)`, `searchToString(config, input)`, `encodeStaticParams(route, params)` for `generateStaticParams`/`getStaticPaths`.
+`href` returns `Href` — a string subtype accepted by `next/link`, `router.push`, `redirect` unchanged. Required params/search make the options argument required; defaulted/optional/array keys are omittable. Serialization failures (bad value, empty segment, required catch-all given `[]`) throw `SerializeError` at link-build time. A route defined with `trailingSlash: true` (match `next.config`'s `trailingSlash`) builds `/asset/?q=1` instead of `/asset?q=1`; the root stays `/` and the path literal never ends in `/`. When every route needs it, re-export a typed wrapper (`export const defineAppRoute: typeof defineRoute = (path, config) => defineRoute(path, { trailingSlash: true, ...config });`) instead of repeating it. The string form `href("/about")` has no route object, so it never adds the slash: in a `trailingSlash` app, link through the route object. In tests, set `process.env.__NEXT_TRAILING_SLASH = "true"`, or `next/link` strips the slash from rendered hrefs. Lower-level pieces: `buildPath(route, params)`, `searchToString(config, input)`, `encodeStaticParams(route, params)` for `generateStaticParams`/`getStaticPaths`.
 
 ## Client hooks
 

package/skills/paramour/references/migration.md

@@ -76,7 +76,7 @@ export default async function ProductPage(props: RouteProps) {
 - `sp.x ?? "default"` / `Number(sp.x ?? "1")` → codec with `.default(value)`. The decoded field is non-optional and the default value elides from built URLs.
 - "May be absent, no fallback" (`typeof sp.x === "string" ? sp.x : undefined`) → `.optional()`. Decoded as `T | undefined`.
 - Silent-coercion tolerance (old code shrugged off garbage, e.g. `Number(...)` producing `NaN` handled downstream) → add `.catch(fallback)` so a malformed PRESENT value falls back instead of failing the decode. `.catch()` never covers absence — combine with `.default()`/`.optional()` for that.
-- Multi-value keys (`sp.tags` handled as `string | string[]`) → `p.array()` for repeated keys (`?tags=a&tags=b`) or `p.csv()` for one comma-joined key (`?tags=a,b`). Match whichever wire form the app already emits.
+- Multi-value keys (`sp.tags` handled as `string | string[]`) → `p.array()` for repeated keys (`?tags=a&tags=b`) or `p.csv()` for one comma-joined key (`?tags=a,b`). Match whichever wire form the app already emits. Lists that nuqs's `parseAsArrayOf` already wrote (elements with `%2C`-escaped commas, bad elements dropped) → `nuqsArrayOf(element)` from `@paramour-js/nuqs`, not `p.csv()`.
 - Enumerated strings → `p.enum(["a", "b"])`; numbers → `p.number()`; booleans (`sp.flag === "true"`) → `p.boolean()`; dates → `p.isoDate()` (YYYY-MM-DD) or `p.timestamp()` (ISO instant; emits UTC).
 
 ### Behavior change to decide explicitly