fix: infer route types across the middleware/validator module cycle

.changeset/middleware-validator-type-cycle.md

@@ -0,0 +1,5 @@
+---
+"@marko/run": patch
+---
+
+Fix route middleware and handler types collapsing to `any` when a middleware derives `next()` data from its context while a downstream handler declares validators.

agent-feedback/dx.md

@@ -209,9 +209,3 @@ CodeRabbit's pre-merge checks (configured in the organization UI; the repo has n
 `cspell.json` › `words` | 2026-08-11 | impact:med | effort:low
 
 `pnpm run lint` fails on a clean `main` with a single cspell error: `agent-feedback/cleanup.md` uses "macrotask", which is not in `cspell.json`'s `words` list. The word arrived with 445114c (#256) and the check covers `**/*.{md,ts,marko}`, so every branch cut from main inherits a red lint until the word is added. Re-verify: `npx cspell "**/*.{md,ts,marko}" --no-progress` on main reports one issue.
-
-## A `params` validator on a route with two `$` segments loses its typing
-
-`packages/run/src/runtime/types.ts` › `RouteForFileDef` | 2026-08-17 | impact:low | effort:med
-
-In an app with `api/workspaces/$id/+middleware.ts` (a `Run.ALL` middleware calling `next({ workspace })`) and a leaf `api/workspaces/$id/review/$commentId/+handler.ts` exporting `Run.DELETE({ params({ id, commentId }) { … } }, (ctx) => …)`, `tsc` reports TS7031 (`id` / `commentId` implicitly any) on the validator's destructured argument and TS2554 ("Expected 1 arguments, but got 2") on the `Run.DELETE` call, so the two-argument form is unusable there. The identical shape on a one-segment route with no parent middleware (`api/procs/$pid/+handler.ts`, `Run.DELETE({ params({ pid }) … }, handler)`) type-checks. Something in the merge of the parent middleware's options with the leaf's `params` (`MergedRouteOptionsForFile` → `RouteForFileDef.params`) collapses when the path has two params, since the workaround is simply parsing `ctx.params.commentId` inside the handler. Repro: the two files above in a fixture under `packages/run/src/__tests__/fixtures/`, then `tsc` on it; a passing fixture with the validator form is the fix's test.

packages/run/src/__tests__/fixtures/params-validator-types/.marko-run/routes.d.ts

@@ -0,0 +1,87 @@
+/*
+  WARNING: This file is automatically generated and any changes made to it will be overwritten without warning.
+  Do NOT manually edit this file or your changes will be lost.
+*/
+
+import { NotHandled, NotMatched, GetPaths, PostPaths, GetablePath, GetableHref, PostablePath, PostableHref, Platform } from "@marko/run/namespace";
+import type * as $ from "@marko/run";
+
+
+declare module "@marko/run" {
+	interface App extends $.DefineRoutes<{
+		"/api/procs/$pid": [H1];
+		"/api/workspaces/$id/review/$commentId": [M1, H2];
+	}> {}
+}
+
+type M1 = $.Middleware<"M1", typeof import("../src/routes/api/workspaces/$id/+middleware")>;
+declare module "../src/routes/api/workspaces/$id/+middleware" {
+  const Run: $.Namespace<M1>;
+  namespace Run {
+    type Context = $.ContextForFile<M1>;
+  }
+
+  /** @deprecated use `Run` namespace instead */
+  namespace MarkoRun {
+    export { NotHandled, NotMatched, GetPaths, PostPaths, GetablePath, GetableHref, PostablePath, PostableHref, Platform };
+    export type Route = $.Routes["/api/workspaces/$id/review/$commentId"];
+    export type Context = $.MultiRouteContext<Route>;
+    export type Handler = $.HandlerLike<Route>;
+    export type GET = $.HandlerLike<Route, "GET">;
+    export type HEAD = $.HandlerLike<Route, "HEAD">;
+    export type POST = $.HandlerLike<Route, "POST">;
+    export type PUT = $.HandlerLike<Route, "PUT">;
+    export type DELETE = $.HandlerLike<Route, "DELETE">;
+    export type PATCH = $.HandlerLike<Route, "PATCH">;
+    export type OPTIONS = $.HandlerLike<Route, "OPTIONS">;
+    export type QUERY = $.HandlerLike<Route, "QUERY">;
+  }
+}
+
+type H1 = $.Handler<"H1", typeof import("../src/routes/api/procs/$pid/+handler")>;
+declare module "../src/routes/api/procs/$pid/+handler" {
+  const Run: $.Namespace<H1>;
+  namespace Run {
+    type Context = $.ContextForFile<H1>;
+  }
+
+  /** @deprecated use `Run` namespace instead */
+  namespace MarkoRun {
+    export { NotHandled, NotMatched, GetPaths, PostPaths, GetablePath, GetableHref, PostablePath, PostableHref, Platform };
+    export type Route = $.Routes["/api/procs/$pid"];
+    export type Context = $.MultiRouteContext<Route>;
+    export type Handler = $.HandlerLike<Route>;
+    export type GET = $.HandlerLike<Route, "GET">;
+    export type HEAD = $.HandlerLike<Route, "HEAD">;
+    export type POST = $.HandlerLike<Route, "POST">;
+    export type PUT = $.HandlerLike<Route, "PUT">;
+    export type DELETE = $.HandlerLike<Route, "DELETE">;
+    export type PATCH = $.HandlerLike<Route, "PATCH">;
+    export type OPTIONS = $.HandlerLike<Route, "OPTIONS">;
+    export type QUERY = $.HandlerLike<Route, "QUERY">;
+  }
+}
+
+type H2 = $.Handler<"H2", typeof import("../src/routes/api/workspaces/$id/review/$commentId/+handler")>;
+declare module "../src/routes/api/workspaces/$id/review/$commentId/+handler" {
+  const Run: $.Namespace<H2>;
+  namespace Run {
+    type Context = $.ContextForFile<H2>;
+  }
+
+  /** @deprecated use `Run` namespace instead */
+  namespace MarkoRun {
+    export { NotHandled, NotMatched, GetPaths, PostPaths, GetablePath, GetableHref, PostablePath, PostableHref, Platform };
+    export type Route = $.Routes["/api/workspaces/$id/review/$commentId"];
+    export type Context = $.MultiRouteContext<Route>;
+    export type Handler = $.HandlerLike<Route>;
+    export type GET = $.HandlerLike<Route, "GET">;
+    export type HEAD = $.HandlerLike<Route, "HEAD">;
+    export type POST = $.HandlerLike<Route, "POST">;
+    export type PUT = $.HandlerLike<Route, "PUT">;
+    export type DELETE = $.HandlerLike<Route, "DELETE">;
+    export type PATCH = $.HandlerLike<Route, "PATCH">;
+    export type OPTIONS = $.HandlerLike<Route, "OPTIONS">;
+    export type QUERY = $.HandlerLike<Route, "QUERY">;
+  }
+}

packages/run/src/__tests__/fixtures/params-validator-types/__snapshots__/dev.expected.md

@@ -0,0 +1,5 @@
+# Loading
+
+# Step 0
+ctx=>deleteComment(ctx)
+

packages/run/src/__tests__/fixtures/params-validator-types/__snapshots__/preview.expected.md

@@ -0,0 +1,5 @@
+# Loading
+
+# Step 0
+ctx=>deleteComment(ctx)
+

packages/run/src/__tests__/fixtures/params-validator-types/src/routes/api/procs/$pid/+handler.ts

@@ -0,0 +1,21 @@
+export const DELETE = Run.DELETE(
+  {
+    params({ pid }) {
+      return { pid };
+    },
+  },
+  (ctx) => {
+    return Response.json({ pid: ctx.params.pid });
+  },
+);
+
+// No middleware runs upstream, so this file's handlers get return checking.
+export const validReturns = [
+  Run.GET(() => new Response("ok")),
+  Run.GET(async () => Response.json({ ok: true })),
+  Run.GET((ctx, next) => next()),
+];
+// @ts-expect-error a handler cannot return a bare number
+export const badNumber = Run.GET(() => 42);
+// @ts-expect-error a handler cannot return a bare object in place of a Response
+export const badObject = Run.GET(() => ({ plain: "object" }));

packages/run/src/__tests__/fixtures/params-validator-types/src/routes/api/workspaces/$id/+middleware.ts

@@ -0,0 +1,16 @@
+export default Run.ALL(
+  {
+    search({ limit }) {
+      return { limit: limit ? Number(limit) : 0 };
+    },
+  },
+  (ctx, next) => {
+    if ("commentId" in ctx.params) {
+      const merged: number = ctx.params.commentId;
+      // @ts-expect-error the DELETE validator types commentId as number
+      const bad: boolean = ctx.params.commentId;
+      void merged, void bad;
+    }
+    return next({ workspace: `ws-${ctx.params.id}` });
+  },
+);

packages/run/src/__tests__/fixtures/params-validator-types/src/routes/api/workspaces/$id/review/$commentId/+handler.ts

@@ -0,0 +1,37 @@
+import type { Context, GetContext } from "@marko/run";
+
+export const DELETE = Run.DELETE(
+  {
+    params({ id, commentId }) {
+      return { id, commentId: Number(commentId) };
+    },
+  },
+  (ctx) => {
+    const asPlainContext: Context = ctx;
+    const asScopedContext: GetContext<"/api/workspaces/$id/review/$commentId"> =
+      ctx;
+    // @ts-expect-error the deprecated MarkoRun.Context types params as raw
+    // strings, so a context whose validator produced a number never fit it
+    const asLegacyContext: MarkoRun.Context = ctx;
+    void asPlainContext, void asScopedContext, void asLegacyContext;
+    const validated: number = ctx.params.commentId;
+    const upstream: string = ctx.data.workspace;
+    const fromMiddleware: number = ctx.search.limit;
+    // @ts-expect-error the validator types commentId as number
+    const badParam: boolean = ctx.params.commentId;
+    // @ts-expect-error the middleware data types workspace as string
+    const badData: boolean = ctx.data.workspace;
+    // @ts-expect-error the middleware search validator types limit as number
+    const badSearch: boolean = ctx.search.limit;
+    void validated, void upstream, void fromMiddleware, void badParam;
+    void badData, void badSearch;
+    return Response.json({
+      id: ctx.params.id,
+      commentId: ctx.params.commentId,
+    });
+  },
+);
+
+export const routeLevel: number = null as unknown as Run.Context["params"]["commentId"];
+// @ts-expect-error route-level params keep the validated number type
+export const routeLevelBad: boolean = null as unknown as Run.Context["params"]["commentId"];

packages/run/src/__tests__/fixtures/params-validator-types/test.config.ts

@@ -0,0 +1,15 @@
+import assert from "assert";
+
+import type { Step, StepContext } from "../../main.test";
+
+export const path = "/api/procs/42";
+
+async function deleteComment({ page }: StepContext) {
+  const res = await page.fetch(
+    new URL("/api/workspaces/w1/review/7", page.url()).href,
+    { method: "DELETE" },
+  );
+  assert.deepEqual(await res.json(), { id: "w1", commentId: 7 });
+}
+
+export const steps: Step[] = [(ctx) => deleteComment(ctx)];

packages/run/src/__tests__/fixtures/params-validator-types/tsconfig.check.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@marko/run": ["../../../runtime/index.ts"],
+      "@marko/run/namespace": ["../../../runtime/namespace.ts"]
+    }
+  }
+}

packages/run/src/__tests__/fixtures/params-validator-types/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig-base.json",
+  "include": ["src/**/*", ".marko-run/*"],
+}

packages/run/src/__tests__/typecheck.test.ts

@@ -57,3 +57,37 @@ describe("test sources type-check", () => {
     );
   });
 });
+
+describe("route type generation type-checks", () => {
+  // The fixture's middleware and handler each need the other's inferred
+  // module type — the shape that collapses both to `any` (TS7022). Its
+  // `@ts-expect-error` probes make silent widening fail this compile too.
+  it("keeps middleware and validator types across the module cycle", function () {
+    this.timeout(120000);
+    const result = spawnSync(
+      process.execPath,
+      [
+        require.resolve("typescript/lib/tsc.js"),
+        "-p",
+        path.join(
+          __dirname,
+          "fixtures",
+          "params-validator-types",
+          "tsconfig.check.json",
+        ),
+        "--pretty",
+        "false",
+      ],
+      { encoding: "utf-8", timeout: 90000 },
+    );
+
+    const localErrors = (result.stdout || "")
+      .split("\n")
+      // The compile pulls in the whole workspace graph, which carries known
+      // declaration-level noise; only errors in the fixture's sources are
+      // the reproduction.
+      .filter((line) => /params-validator-types[/\\]src[/\\]/.test(line));
+
+    assert.deepEqual(localErrors, []);
+  });
+});

packages/run/src/runtime/index.ts

@@ -77,10 +77,15 @@ export type {
 export type {
   App,
   Context,
+  ContextBase,
   ContextForFile,
+  DefinedHandler,
+  DefinedHandlerTypes,
+  DefineHandler,
   DefineRoutes,
   Empty,
   Fetch,
+  FileContext,
   GetContext,
   Handler,
   HandlerTypes,