@paramour-js/next 0.9.0 → 0.11.0

package/dist/doctor/checks.js

@@ -5,7 +5,7 @@ import { message } from "../cli-io.js";
 import { loadConfigFile } from "../config.js";
 import { checkArtifact, formatRouteDiff, } from "../generate.js";
 import { tsconfigCheck } from "../init/scaffold.js";
-import { detectWrapState, findNextConfig } from "../init/wrap-next-config.js";
+import { detectWrapState, findNextConfig, readTrailingSlash, } from "../init/wrap-next-config.js";
 import { discoverRouteDefinitions, routeKey, } from "../list/discover-route-defs.js";
 import { scanRoutes } from "../scan.js";
 import { skillsDoctorChecks } from "../skills/doctor.js";
@@ -151,7 +151,16 @@ export async function runDoctorChecks(projectRoot) {
         status: coverage.ok ? "pass" : "warn",
     });
     // 8. Route-definition discovery health (list's engine).
-    checks.push(await discoveryCheck(projectRoot, config, routes));
+    const discovered = await discoveryCheck(projectRoot, config, routes);
+    checks.push(discovered.check);
+    // 9. Route definitions build the URLs next.config serves. Reported only
+    // when there is an answer: definitions exist and the config's
+    // trailingSlash reads statically.
+    if (nextConfig !== undefined && discovered.definitions.length > 0) {
+        const check = await trailingSlashCheck(nextConfig.path, discovered.definitions);
+        if (check !== undefined)
+            checks.push(check);
+    }
     return checks;
 }
 async function discoveryCheck(projectRoot, config, routes) {
@@ -177,18 +186,24 @@ async function discoveryCheck(projectRoot, config, routes) {
             detail.push(`duplicate definition of ${duplicate.path} (${duplicate.router}) in ${duplicate.file} — ${duplicate.firstFile} wins`);
         }
         return {
-            detail,
-            label: `route definitions: ${String(discovery.definitions.length)} found in ${String(files.size)} module${files.size === 1 ? "" : "s"}`,
-            status: discovery.loadFailures.length > 0 || discovery.duplicates.length > 0
-                ? "warn"
-                : "pass",
+            check: {
+                detail,
+                label: `route definitions: ${String(discovery.definitions.length)} found in ${String(files.size)} module${files.size === 1 ? "" : "s"}`,
+                status: discovery.loadFailures.length > 0 || discovery.duplicates.length > 0
+                    ? "warn"
+                    : "pass",
+            },
+            definitions: discovery.definitions,
         };
     }
     catch (error) {
         return {
-            detail: [message(error)],
-            label: "route definitions: discovery failed",
-            status: "warn",
+            check: {
+                detail: [message(error)],
+                label: "route definitions: discovery failed",
+                status: "warn",
+            },
+            definitions: [],
         };
     }
 }
@@ -206,6 +221,43 @@ function readManifest(projectRoot, name) {
         }
     }
 }
+/**
+ * Warn-level: a route whose `trailingSlash` disagrees with next.config's
+ * builds a URL the app only reaches through a redirect (or, in a static
+ * export, a path with no file behind it). `undefined` when the config's value
+ * cannot be read statically — no finding beats a guessed one.
+ */
+async function trailingSlashCheck(nextConfigPath, definitions) {
+    let configured;
+    try {
+        configured = await readTrailingSlash(readFileSync(nextConfigPath, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (configured === undefined)
+        return undefined;
+    const name = basename(nextConfigPath);
+    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);
+    if (mismatched.length === 0) {
+        return {
+            label: `trailing slash: route definitions match ${name} (${setting})`,
+            status: "pass",
+        };
+    }
+    const fix = configured
+        ? "add trailingSlash: true to its definition"
+        : "remove trailingSlash: true from its definition";
+    return {
+        detail: mismatched.map((definition) => `${definition.route.path} (${definition.route["~router"]}) in ${definition.file}: ${fix}`),
+        label: `trailing slash: ${String(mismatched.length)} route definition${mismatched.length === 1 ? "" : "s"} disagree${mismatched.length === 1 ? "s" : ""} with ${name} (${setting})`,
+        status: "warn",
+    };
+}
 function versionCheck(projectRoot) {
     const coreManifest = readManifest(projectRoot, "paramour");
     const nextManifest = readManifest(projectRoot, "@paramour-js/next");

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

@@ -28,6 +28,16 @@ export declare function detectWrapState(source: string): Promise<"not-wrapped" |
 export declare function findNextConfig(projectRoot: string): FoundNextConfig | undefined;
 /** The `manual` fallback text — also printed when no config file exists. */
 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.
+ */
+export declare function readTrailingSlash(source: string): Promise<boolean | undefined>;
 /**
  * The transform: add the named import (unless present under any alias) and
  * rewrap the default export — identifier, object literal, existing wrapper

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

@@ -41,6 +41,49 @@ export function manualSnippet() {
         "export default withTypedRoutes(nextConfig);",
     ].join("\n");
 }
+/**
+ * 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.
+ */
+export async function readTrailingSlash(source) {
+    const { parseModule } = await import("magicast");
+    let program;
+    try {
+        program = parseModule(source).$ast;
+    }
+    catch {
+        return undefined;
+    }
+    const body = asNodes(program.body);
+    const bindings = new Map();
+    let exported;
+    for (const statement of body) {
+        if (statement.type === "VariableDeclaration") {
+            for (const declarator of asNodes(statement.declarations)) {
+                const id = asNode(declarator.id);
+                if (id?.type === "Identifier" && typeof id.name === "string") {
+                    bindings.set(id.name, declarator.init);
+                }
+            }
+        }
+        else if (statement.type === "ExportDefaultDeclaration") {
+            exported = statement.declaration;
+        }
+        else if (statement.type === "ExpressionStatement") {
+            const expression = asNode(statement.expression);
+            if (expression?.type === "AssignmentExpression" &&
+                isModuleExports(asNode(expression.left))) {
+                exported = expression.right;
+            }
+        }
+    }
+    return trailingSlashOf(exported, bindings, 0);
+}
 /**
  * The transform: add the named import (unless present under any alias) and
  * rewrap the default export — identifier, object literal, existing wrapper
@@ -82,6 +125,28 @@ export async function wrapNextConfigSource(source) {
         return { snippet: manualSnippet(), status: "manual" };
     }
 }
+function asNode(value) {
+    return typeof value === "object" &&
+        value !== null &&
+        typeof value.type === "string"
+        ? value
+        : undefined;
+}
+function asNodes(value) {
+    return Array.isArray(value)
+        ? value.flatMap((item) => asNode(item) ?? [])
+        : [];
+}
+function isModuleExports(node) {
+    if (node?.type !== "MemberExpression" || node.computed === true)
+        return false;
+    const object = asNode(node.object);
+    const property = asNode(node.property);
+    return (object?.type === "Identifier" &&
+        object.name === "module" &&
+        property?.type === "Identifier" &&
+        property.name === "exports");
+}
 function isWrappedCall(value, local) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -94,6 +159,65 @@ function isWrappedCall(value, local) {
         ((local !== undefined && node.$callee === local) ||
             node.$callee.endsWith(".withTypedRoutes")));
 }
+function propertyName(node) {
+    if (node.computed === true)
+        return undefined;
+    const key = asNode(node.key);
+    if (key?.type === "Identifier" && typeof key.name === "string") {
+        return key.name;
+    }
+    if (key?.type === "StringLiteral" && typeof key.value === "string") {
+        return key.value;
+    }
+    return undefined;
+}
+/**
+ * One resolution step of {@link readTrailingSlash}. The depth bound stops a
+ * self-referencing binding (`const a = f(a)`) from looping.
+ */
+function trailingSlashOf(value, bindings, depth) {
+    const node = asNode(value);
+    if (node === undefined || depth > 16)
+        return undefined;
+    switch (node.type) {
+        case "CallExpression": {
+            const [first] = asNodes(node.arguments);
+            return trailingSlashOf(first, bindings, depth + 1);
+        }
+        case "Identifier": {
+            return typeof node.name === "string" && bindings.has(node.name)
+                ? trailingSlashOf(bindings.get(node.name), bindings, depth + 1)
+                : undefined;
+        }
+        case "ObjectExpression": {
+            // Last write wins, as at runtime; any spread could carry the key.
+            let result = false;
+            for (const property of asNodes(node.properties)) {
+                if (property.type === "SpreadElement")
+                    return undefined;
+                if (propertyName(property) !== "trailingSlash")
+                    continue;
+                const literal = asNode(property.value);
+                result =
+                    property.type === "ObjectProperty" &&
+                        literal?.type === "BooleanLiteral" &&
+                        typeof literal.value === "boolean"
+                        ? literal.value
+                        : undefined;
+            }
+            return result;
+        }
+        case "ParenthesizedExpression":
+        case "TSAsExpression":
+        case "TSNonNullExpression":
+        case "TSSatisfiesExpression": {
+            return trailingSlashOf(node.expression, bindings, depth + 1);
+        }
+        default: {
+            return undefined;
+        }
+    }
+}
 function withTypedRoutesLocal(items) {
     return items.find((item) => item.from === "@paramour-js/next" && item.imported === "withTypedRoutes")?.local;
 }

package/package.json

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

@@ -27,18 +27,18 @@ Wire grammars are strict and anchored — no `Number()` coercion, no whitespace,
 
 ## Modifier chains
 
-| Modifier                        | Effect on decode                                                     | Effect on href input | Effect on URL                                                                                      |
-| ------------------------------- | -------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
-| (none — required)               | Absent key is a decode issue                                         | Key required         | Always emitted when building                                                                       |
-| `.optional()`                   | Absent → `undefined`; field type `T \| undefined`                    | Key omittable        | Omitted key emits nothing                                                                          |
-| `.default(value)`               | Absent → default; field type stays `T`                               | Key omittable        | Value equal to the default ELIDES (compared by serialized wire form) — one canonical URL per state |
-| `.default(() => value)`         | Absent → factory result; field type stays `T`                        | Key omittable        | NEVER elides (a time-varying factory would swallow explicit values)                                |
-| `.catch(v)` / `.catch(() => v)` | A PRESENT value that fails parsing → fallback. Never covers absence. | No change            | No change                                                                                          |
+| Modifier                        | Effect on decode                                                                                                                                | Effect on href input | Effect on URL                                                                                      |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
+| (none — required)               | Absent key is a decode issue                                                                                                                    | Key required         | Always emitted when building                                                                       |
+| `.optional()`                   | Absent → `undefined`; field type `T \| undefined`                                                                                               | Key omittable        | Omitted key emits nothing                                                                          |
+| `.default(value)`               | Absent → default; field type stays `T`                                                                                                          | Key omittable        | Value equal to the default ELIDES (compared by serialized wire form) — one canonical URL per state |
+| `.default(() => value)`         | Absent → factory result; field type stays `T`                                                                                                   | Key omittable        | NEVER elides (a time-varying factory would swallow explicit values)                                |
+| `.catch(v)` / `.catch(() => v)` | A PRESENT value that fails parsing → fallback. Never covers absence. After `.optional()`, the fallback may be `undefined` (bad value → absent). | No change            | No change                                                                                          |
 
 Legality (compile-time type-state — illegal calls type as `never`; runtime throws for JS):
 
-- Legal: `p.integer()`, `.optional()`, `.default(1)`, `.catch(0)`, `.optional().catch(0)`, `.catch(0).optional()`, `.default(1).catch(0)`, `.catch(0).default(1)`, `p.csv().default([])`, `p.array().catch([])`.
-- Illegal: `.optional().default(...)`, `.default(...).optional()`, `.optional().optional()`, `.default(...).default(...)`, `.catch(...).catch(...)`, `p.array().optional()`, `p.array().default(...)`, any modifier on a csv/array ELEMENT (`p.csv(p.string().optional())`), `p.csv(p.csv())`, `p.array(p.array())`, and `.default(value)` where the value's type includes a function member (use the factory form).
+- Legal: `p.integer()`, `.optional()`, `.default(1)`, `.catch(0)`, `.optional().catch(0)`, `.optional().catch(undefined)`, `.catch(0).optional()`, `.default(1).catch(0)`, `.catch(0).default(1)`, `p.csv().default([])`, `p.array().catch([])`.
+- Illegal: `.optional().default(...)`, `.default(...).optional()`, `.optional().optional()`, `.default(...).default(...)`, `.catch(...).catch(...)`, `.catch(undefined)` on a required/defaulted codec (apply `.optional()` first), `p.array().optional()`, `p.array().default(...)`, any modifier on a csv/array ELEMENT (`p.csv(p.string().optional())`), `p.csv(p.csv())`, `p.array(p.array())`, and `.default(value)` where the value's type includes a function member (use the factory form).
 - `params:` codecs additionally forbid `.optional()`/`.default()` (path optionality comes from `[[...slug]]`); `.catch()` is fine.
 
 Value vs factory `.default()`: value defaults are serialized eagerly at definition time (an invalid default fails immediately) and participate in URL elision; factory defaults are invoked per decode (fresh reference per call — use for mutable objects) and never elide. Array value defaults are handed out as fresh shallow copies per decode.
@@ -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. 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 `/`. Lower-level pieces: `buildPath(route, params)`, `searchToString(config, input)`, `encodeStaticParams(route, params)` for `generateStaticParams`/`getStaticPaths`.
 
 ## Client hooks
 

package/skills/paramour/references/reference.md

@@ -76,15 +76,15 @@ Precedence: CLI flags → config file → discovery. Unknown keys are rejected (
 
 ## Wire-format summary (numbered spec: docs/reference/wire-format on paramour.dev)
 
-| Family | Scope                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| S      | Byte layer: `%20` never `+` (S2); absence = omitted key, `""` = `key=` (S3); never bare `?flag` (S4); deterministic declaration order (S5); hash only from `href`'s explicit option, verbatim (S10)                                                                                                                                                                                          |
-| P      | Parse layer: duplicate values on a scalar codec are an error, catchable (P5); absent array key → `[]` (P6); unknown keys ignored and never validated (P8)                                                                                                                                                                                                                                    |
-| SS     | `rawSearch`: explicit wrapper only; schema sees every key on decode; encode is a raw pass-through, schema never runs; no elision/round-trip                                                                                                                                                                                                                                                  |
-| D      | Codec grammar: `.catch()` recovers parse failures never absence (D2); presence governs absence and every declared key appears in decode output (D4); params take no presence modifiers (D5); a catch-all codec describes one element (D6); value defaults elide (D8)                                                                                                                         |
-| CV     | `p.csv`: one comma-joined wire value; `""` ↔ `[]`; empty elements are parse failures; serialize rejects elements that are empty or contain commas                                                                                                                                                                                                                                            |
-| R      | Route segments: one segment per `[param]` (R1); catch-all elements encode independently, inner `/` → `%2F` (R2); optional catch-all elides, required `[]` is a `SerializeError` (R3); empty segment value is a `SerializeError` (R4); App Router param props arrive percent-ENCODED and core decodes them — Pages surfaces opt out via `percentDecode: false` (R5); no trailing slashes (R6) |
-| PP     | `p.array` typed elements by composition (PP1); `p.index` is 1-based on the wire, 0-based in memory (PP5)                                                                                                                                                                                                                                                                                     |
+| Family | Scope                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| S      | Byte layer: `%20` never `+` (S2); absence = omitted key, `""` = `key=` (S3); never bare `?flag` (S4); deterministic declaration order (S5); hash only from `href`'s explicit option, verbatim (S10)                                                                                                                                                                                                                                                                                                   |
+| P      | Parse layer: duplicate values on a scalar codec are an error, catchable (P5); absent array key → `[]` (P6); unknown keys ignored and never validated (P8)                                                                                                                                                                                                                                                                                                                                             |
+| SS     | `rawSearch`: explicit wrapper only; schema sees every key on decode; encode is a raw pass-through, schema never runs; no elision/round-trip                                                                                                                                                                                                                                                                                                                                                           |
+| D      | Codec grammar: `.catch()` recovers parse failures never absence (D2); presence governs absence and every declared key appears in decode output (D4); params take no presence modifiers (D5); a catch-all codec describes one element (D6); value defaults elide (D8)                                                                                                                                                                                                                                  |
+| CV     | `p.csv`: one comma-joined wire value; `""` ↔ `[]`; empty elements are parse failures; serialize rejects elements that are empty or contain commas                                                                                                                                                                                                                                                                                                                                                     |
+| R      | Route segments: one segment per `[param]` (R1); catch-all elements encode independently, inner `/` → `%2F` (R2); optional catch-all elides, required `[]` is a `SerializeError` (R3); empty segment value is a `SerializeError` (R4); App Router param props arrive percent-ENCODED and core decodes them — Pages surfaces opt out via `percentDecode: false` (R5); no trailing slashes (R6), unless the route sets `trailingSlash: true`, which ends every non-root built path in `/` before `?`/`#` |
+| PP     | `p.array` typed elements by composition (PP1); `p.index` is 1-based on the wire, 0-based in memory (PP5)                                                                                                                                                                                                                                                                                                                                                                                              |
 
 Facts agents trip on: