@warlock.js/core 4.16.0 → 5.0.1

package/esm/router/positional-handler-diagnostics.d.mts

@@ -0,0 +1,90 @@
+import { Route } from "./types.mjs";
+import { log } from "@warlock.js/logger";
+
+//#region ../core/src/router/positional-handler-diagnostics.d.ts
+/**
+ * One route whose handler looks like it was written for v4.
+ */
+type PositionalHandlerSuspect = {
+  /** HTTP method the route was registered under. */method: Route["method"]; /** Full route path, prefixes already applied. */
+  path: string; /** Handler function name, or `"(anonymous)"` when it has none. */
+  handlerName: string; /** Route file the route came from, when the router knows it. */
+  sourceFile: string;
+};
+/**
+ * Does this handler look like it was written for the v4 positional signature?
+ *
+ * ## The signal, and what it misses
+ *
+ * `Function.length` alone is not enough, because it stops counting at the first
+ * defaulted parameter:
+ *
+ * | handler                            | `.length` | actually |
+ * | ---------------------------------- | --------- | -------- |
+ * | `({ request, response }) => …`     | 1         | v5       |
+ * | `(ctx) => …`                       | 1         | v5       |
+ * | `(request, response) => …`         | 2         | v4       |
+ * | `(request, response = x) => …`     | 1         | v4       |
+ *
+ * So the primary signal is the function's own source: a handler is suspect when
+ * it declares **two or more** parameters and the first is **not** destructured.
+ * Reading the source catches the defaulted row that arity cannot, and rules out
+ * the `({ … }, extra)` shape that arity would wrongly flag.
+ *
+ * When the source is unreadable — a bound or native function — this falls back
+ * to `handler.length >= 2`, which `bind` preserves. That is a weaker signal but
+ * never a wrong one for the common cases; it only loses the defaulted row.
+ *
+ * ## What is still missed, by design
+ *
+ * A one-parameter v4 handler (`(request) => …`) is indistinguishable from a v5
+ * `(ctx) => …` and is deliberately not flagged — guessing there would produce
+ * false positives on correct code. False positives against the canonical
+ * `({ … })` form are essentially nil, and every miss simply leaves today's
+ * behaviour in place.
+ */
+declare function looksLikePositionalHandler(handler: unknown): boolean;
+/**
+ * Inspect one route's handler as it registers, recording it when it looks like
+ * the v4 positional form. Called from `Router.add`, so the cost is paid once per
+ * route at registration and never per request.
+ *
+ * Deliberately total: any unexpected failure in the heuristic is swallowed, so a
+ * diagnostic can never be the reason a route fails to register.
+ */
+declare function inspectHandlerSignature(handler: unknown, route: {
+  method: Route["method"];
+  path: string;
+  sourceFile: string;
+}): void;
+/**
+ * Every suspect recorded so far, in registration order.
+ */
+declare function listPositionalHandlerSuspects(): readonly PositionalHandlerSuspect[];
+/**
+ * Drop the suspects belonging to a route file. Kept in step with
+ * `Router.removeRoutesBySourceFile` so an HMR reload that fixes a handler does
+ * not keep reporting the version it replaced.
+ */
+declare function forgetPositionalHandlerSuspects(sourceFile: string): void;
+/**
+ * Drop every recorded suspect. Intended for tests, which share the router
+ * singleton.
+ */
+declare function clearPositionalHandlerSuspects(): void;
+/**
+ * The one-line diagnostic for a single route. Written for someone who has never
+ * read Warlock's internals: it names the handler, the route, what is wrong, and
+ * the exact edit that fixes it.
+ */
+declare function describePositionalHandlerSuspect(suspect: PositionalHandlerSuspect): string;
+/**
+ * The full boot-time warning: every suspect, once, in one entry.
+ *
+ * One boot, one list — not one warning per route, and emphatically not one 500
+ * per request. Returns the reported suspects so callers can assert on them.
+ */
+declare function reportPositionalHandlerSuspects(logger?: Pick<typeof log, "warn">): PositionalHandlerSuspect[];
+//#endregion
+export { PositionalHandlerSuspect, clearPositionalHandlerSuspects, describePositionalHandlerSuspect, forgetPositionalHandlerSuspects, inspectHandlerSignature, listPositionalHandlerSuspects, looksLikePositionalHandler, reportPositionalHandlerSuspects };
+//# sourceMappingURL=positional-handler-diagnostics.d.mts.map

package/esm/router/positional-handler-diagnostics.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positional-handler-diagnostics.d.mts","names":[],"sources":["../../../../../../../core/src/router/positional-handler-diagnostics.ts"],"mappings":";;;;AAyPsE;AAmBtE;;AAnBsE,KArN1D,wBAAA;EAwOsE,kDAtOhF,MAAA,EAAQ,KAAK,YA+OC;EA5Od,IAAA;EAGA,WAAA,UAyOgE;EAtOhE,UAAA;AAAA;;;AAkP4C;AAS9C;;;;AAAkF;AAclF;;;;;;;;;;;;;AAAsF;;;;;;;;;;;iBAhGtE,0BAAA,CAA2B,OAAgB;;;;;;;;;iBA+B3C,uBAAA,CACd,OAAA,WACA,KAAA;EAAS,MAAA,EAAQ,KAAK;EAAY,IAAA;EAAc,UAAA;AAAA;;;;iBAmBlC,6BAAA,aAA0C,wBAAwB;;;;;;iBASlE,+BAAA,CAAgC,UAAkB;;;;;iBAYlD,8BAAA;;;;;;iBASA,gCAAA,CAAiC,OAAiC,EAAxB,wBAAwB;;;;;;;iBAclE,+BAAA,CAAgC,MAAA,GAAQ,IAAA,QAAY,GAAA,YAAkB,wBAAA"}

package/esm/router/positional-handler-diagnostics.mjs

@@ -0,0 +1,247 @@
+import { log } from "@warlock.js/logger";
+
+//#region ../core/src/router/positional-handler-diagnostics.ts
+/**
+* Early detection of route handlers still written against the **v4 positional
+* signature** — `(request, response)` — after v5 moved to a single context
+* object, `({ request, response })`.
+*
+* ## Why this exists
+*
+* A v4 handler is not rejected anywhere. It registers fine, and the router
+* calls it with one argument, so `response` is simply `undefined`. The app only
+* breaks on the first request that reaches it, with:
+*
+*     TypeError: Cannot read properties of undefined (reading 'success')
+*
+* That message names nothing the reader can act on — not the route, not the
+* handler, not the change to make. This module turns that late, opaque failure
+* into one explicit list printed at boot, and into a `warlock doctor` check.
+*
+* The break itself is intentional; nothing here restores the positional form.
+* Detection and diagnostics only.
+*
+* ## Why it warns and never throws
+*
+* The signal is a heuristic (see {@link looksLikePositionalHandler}), so a
+* false positive is possible in principle. Turning one into a boot failure
+* would take a working application down over a guess, which is strictly worse
+* than the problem being diagnosed. Everything on this path is therefore a
+* warning: nothing here throws, and nothing here changes how a handler is
+* called. A miss simply degrades to the old runtime `TypeError`.
+*/
+/**
+* Collected across the whole registration pass so the warning can be emitted
+* ONCE, as a single list, rather than one line per route (or — as before — one
+* mystery 500 per request).
+*/
+const suspects = [];
+/**
+* Split the parameter list of a function's source into top-level parameters.
+*
+* Depth-aware and quote-aware, because a default value may itself contain
+* commas, parentheses, braces or strings — `(request, response = f(a, b))` is
+* two parameters, not three. Anything unbalanced returns `undefined`: refusing
+* to guess is what keeps a parse quirk from becoming a false warning.
+*
+* @param openIndex index of the `(` that opens the parameter list.
+*/
+function splitTopLevelParameters(source, openIndex) {
+	const parameters = [];
+	let depth = 0;
+	let current = "";
+	let quote = "";
+	for (let index = openIndex; index < source.length; index++) {
+		const char = source[index];
+		if (quote) {
+			if (char === "\\") {
+				current += char + (source[index + 1] ?? "");
+				index++;
+				continue;
+			}
+			if (char === quote) quote = "";
+			current += char;
+			continue;
+		}
+		if (char === "\"" || char === "'" || char === "`") {
+			quote = char;
+			current += char;
+			continue;
+		}
+		if (char === "(" || char === "[" || char === "{") {
+			depth++;
+			if (depth === 1) continue;
+			current += char;
+			continue;
+		}
+		if (char === ")" || char === "]" || char === "}") {
+			depth--;
+			if (depth === 0) {
+				if (current.trim()) parameters.push(current.trim());
+				return parameters;
+			}
+			current += char;
+			continue;
+		}
+		if (char === "," && depth === 1) {
+			parameters.push(current.trim());
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+}
+/**
+* Read a function's declared parameters from its own source.
+*
+* Returns `undefined` whenever the source cannot be trusted, which callers must
+* treat as "no information" rather than "no parameters":
+*
+* - `Function.prototype.bind` replaces the body with `[native code]`, so every
+*   `[Controller, "method"]` tuple handler lands here (the router binds them);
+* - native functions likewise;
+* - a class, whose first `(` belongs to a constructor or a method, not to a
+*   parameter list;
+* - anything that fails to parse.
+*/
+function readParameterList(handler) {
+	let source;
+	try {
+		source = Function.prototype.toString.call(handler);
+	} catch {
+		return;
+	}
+	if (source.includes("[native code]")) return void 0;
+	if (/^\s*class[\s{]/.test(source)) return void 0;
+	const bareArrow = source.match(/^\s*(?:async\s+)?([A-Za-z_$][\w$]*)\s*=>/);
+	if (bareArrow) return [bareArrow[1]];
+	const openIndex = source.indexOf("(");
+	if (openIndex === -1) return void 0;
+	return splitTopLevelParameters(source, openIndex);
+}
+/**
+* Whether a parameter is written as a destructuring pattern — `{ request }` or
+* `[a, b]` — as opposed to a plain name.
+*/
+function isDestructured(parameter) {
+	const start = parameter.trimStart();
+	return start.startsWith("{") || start.startsWith("[");
+}
+/**
+* Does this handler look like it was written for the v4 positional signature?
+*
+* ## The signal, and what it misses
+*
+* `Function.length` alone is not enough, because it stops counting at the first
+* defaulted parameter:
+*
+* | handler                            | `.length` | actually |
+* | ---------------------------------- | --------- | -------- |
+* | `({ request, response }) => …`     | 1         | v5       |
+* | `(ctx) => …`                       | 1         | v5       |
+* | `(request, response) => …`         | 2         | v4       |
+* | `(request, response = x) => …`     | 1         | v4       |
+*
+* So the primary signal is the function's own source: a handler is suspect when
+* it declares **two or more** parameters and the first is **not** destructured.
+* Reading the source catches the defaulted row that arity cannot, and rules out
+* the `({ … }, extra)` shape that arity would wrongly flag.
+*
+* When the source is unreadable — a bound or native function — this falls back
+* to `handler.length >= 2`, which `bind` preserves. That is a weaker signal but
+* never a wrong one for the common cases; it only loses the defaulted row.
+*
+* ## What is still missed, by design
+*
+* A one-parameter v4 handler (`(request) => …`) is indistinguishable from a v5
+* `(ctx) => …` and is deliberately not flagged — guessing there would produce
+* false positives on correct code. False positives against the canonical
+* `({ … })` form are essentially nil, and every miss simply leaves today's
+* behaviour in place.
+*/
+function looksLikePositionalHandler(handler) {
+	if (typeof handler !== "function") return false;
+	const parameters = readParameterList(handler);
+	if (parameters) return parameters.length >= 2 && !isDestructured(parameters[0]);
+	return handler.length >= 2;
+}
+/**
+* The name to print for a handler.
+*
+* `Function.bind` prefixes the name with `"bound "`, and the router binds every
+* `[Controller, "method"]` tuple handler. The bare method name is what the user
+* actually wrote, so that is what gets printed.
+*/
+function handlerDisplayName(handler) {
+	return handler.name?.replace(/^bound /, "").trim() || "(anonymous)";
+}
+/**
+* Inspect one route's handler as it registers, recording it when it looks like
+* the v4 positional form. Called from `Router.add`, so the cost is paid once per
+* route at registration and never per request.
+*
+* Deliberately total: any unexpected failure in the heuristic is swallowed, so a
+* diagnostic can never be the reason a route fails to register.
+*/
+function inspectHandlerSignature(handler, route) {
+	try {
+		if (!looksLikePositionalHandler(handler)) return;
+		suspects.push({
+			method: route.method,
+			path: route.path,
+			handlerName: handlerDisplayName(handler),
+			sourceFile: route.sourceFile
+		});
+	} catch {}
+}
+/**
+* Every suspect recorded so far, in registration order.
+*/
+function listPositionalHandlerSuspects() {
+	return suspects;
+}
+/**
+* Drop the suspects belonging to a route file. Kept in step with
+* `Router.removeRoutesBySourceFile` so an HMR reload that fixes a handler does
+* not keep reporting the version it replaced.
+*/
+function forgetPositionalHandlerSuspects(sourceFile) {
+	for (let index = suspects.length - 1; index >= 0; index--) if (suspects[index].sourceFile === sourceFile) suspects.splice(index, 1);
+}
+/**
+* Drop every recorded suspect. Intended for tests, which share the router
+* singleton.
+*/
+function clearPositionalHandlerSuspects() {
+	suspects.length = 0;
+}
+/**
+* The one-line diagnostic for a single route. Written for someone who has never
+* read Warlock's internals: it names the handler, the route, what is wrong, and
+* the exact edit that fixes it.
+*/
+function describePositionalHandlerSuspect(suspect) {
+	return `Handler "${suspect.handlerName}" (${suspect.method} ${suspect.path}) looks like the v4 positional signature (request, response). v5 passes a single context object — change it to ({ request, response }).`;
+}
+/**
+* The full boot-time warning: every suspect, once, in one entry.
+*
+* One boot, one list — not one warning per route, and emphatically not one 500
+* per request. Returns the reported suspects so callers can assert on them.
+*/
+function reportPositionalHandlerSuspects(logger = log) {
+	const reported = [...suspects];
+	if (reported.length === 0) return reported;
+	const headline = reported.length === 1 ? "1 route handler looks like the v4 positional signature." : `${reported.length} route handlers look like the v4 positional signature.`;
+	logger.warn({
+		module: "router",
+		action: "handlerSignature",
+		message: `${headline} Warlock v5 calls every route handler with a single context object, so a second parameter is always undefined and the request fails as soon as it is used:\n` + reported.map((suspect) => `  - ${describePositionalHandlerSuspect(suspect)}`).join("\n"),
+		context: { handlers: reported }
+	});
+	return reported;
+}
+
+//#endregion
+export { clearPositionalHandlerSuspects, describePositionalHandlerSuspect, forgetPositionalHandlerSuspects, inspectHandlerSignature, listPositionalHandlerSuspects, looksLikePositionalHandler, reportPositionalHandlerSuspects };
+//# sourceMappingURL=positional-handler-diagnostics.mjs.map

package/esm/router/positional-handler-diagnostics.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"positional-handler-diagnostics.mjs","names":[],"sources":["../../../../../../../core/src/router/positional-handler-diagnostics.ts"],"sourcesContent":["/**\n * Early detection of route handlers still written against the **v4 positional\n * signature** — `(request, response)` — after v5 moved to a single context\n * object, `({ request, response })`.\n *\n * ## Why this exists\n *\n * A v4 handler is not rejected anywhere. It registers fine, and the router\n * calls it with one argument, so `response` is simply `undefined`. The app only\n * breaks on the first request that reaches it, with:\n *\n *     TypeError: Cannot read properties of undefined (reading 'success')\n *\n * That message names nothing the reader can act on — not the route, not the\n * handler, not the change to make. This module turns that late, opaque failure\n * into one explicit list printed at boot, and into a `warlock doctor` check.\n *\n * The break itself is intentional; nothing here restores the positional form.\n * Detection and diagnostics only.\n *\n * ## Why it warns and never throws\n *\n * The signal is a heuristic (see {@link looksLikePositionalHandler}), so a\n * false positive is possible in principle. Turning one into a boot failure\n * would take a working application down over a guess, which is strictly worse\n * than the problem being diagnosed. Everything on this path is therefore a\n * warning: nothing here throws, and nothing here changes how a handler is\n * called. A miss simply degrades to the old runtime `TypeError`.\n */\n\nimport { log } from \"@warlock.js/logger\";\nimport type { Route } from \"./types\";\n\n/**\n * One route whose handler looks like it was written for v4.\n */\nexport type PositionalHandlerSuspect = {\n  /** HTTP method the route was registered under. */\n  method: Route[\"method\"];\n\n  /** Full route path, prefixes already applied. */\n  path: string;\n\n  /** Handler function name, or `\"(anonymous)\"` when it has none. */\n  handlerName: string;\n\n  /** Route file the route came from, when the router knows it. */\n  sourceFile: string;\n};\n\n/**\n * Collected across the whole registration pass so the warning can be emitted\n * ONCE, as a single list, rather than one line per route (or — as before — one\n * mystery 500 per request).\n */\nconst suspects: PositionalHandlerSuspect[] = [];\n\n/**\n * Split the parameter list of a function's source into top-level parameters.\n *\n * Depth-aware and quote-aware, because a default value may itself contain\n * commas, parentheses, braces or strings — `(request, response = f(a, b))` is\n * two parameters, not three. Anything unbalanced returns `undefined`: refusing\n * to guess is what keeps a parse quirk from becoming a false warning.\n *\n * @param openIndex index of the `(` that opens the parameter list.\n */\nfunction splitTopLevelParameters(source: string, openIndex: number): string[] | undefined {\n  const parameters: string[] = [];\n\n  let depth = 0;\n  let current = \"\";\n  let quote = \"\";\n\n  for (let index = openIndex; index < source.length; index++) {\n    const char = source[index];\n\n    if (quote) {\n      if (char === \"\\\\\") {\n        current += char + (source[index + 1] ?? \"\");\n        index++;\n        continue;\n      }\n\n      if (char === quote) {\n        quote = \"\";\n      }\n\n      current += char;\n      continue;\n    }\n\n    if (char === '\"' || char === \"'\" || char === \"`\") {\n      quote = char;\n      current += char;\n      continue;\n    }\n\n    if (char === \"(\" || char === \"[\" || char === \"{\") {\n      depth++;\n\n      // The paren that opens the list is punctuation, not part of a parameter.\n      if (depth === 1) continue;\n\n      current += char;\n      continue;\n    }\n\n    if (char === \")\" || char === \"]\" || char === \"}\") {\n      depth--;\n\n      if (depth === 0) {\n        if (current.trim()) {\n          parameters.push(current.trim());\n        }\n\n        return parameters;\n      }\n\n      current += char;\n      continue;\n    }\n\n    if (char === \",\" && depth === 1) {\n      parameters.push(current.trim());\n      current = \"\";\n      continue;\n    }\n\n    current += char;\n  }\n\n  // Never found the closing paren — treat the source as unreadable.\n  return undefined;\n}\n\n/**\n * Read a function's declared parameters from its own source.\n *\n * Returns `undefined` whenever the source cannot be trusted, which callers must\n * treat as \"no information\" rather than \"no parameters\":\n *\n * - `Function.prototype.bind` replaces the body with `[native code]`, so every\n *   `[Controller, \"method\"]` tuple handler lands here (the router binds them);\n * - native functions likewise;\n * - a class, whose first `(` belongs to a constructor or a method, not to a\n *   parameter list;\n * - anything that fails to parse.\n */\nfunction readParameterList(handler: Function): string[] | undefined {\n  let source: string;\n\n  try {\n    source = Function.prototype.toString.call(handler);\n  } catch {\n    return undefined;\n  }\n\n  if (source.includes(\"[native code]\")) return undefined;\n\n  if (/^\\s*class[\\s{]/.test(source)) return undefined;\n\n  // A single parameter needs no parentheses: `ctx => …`, `async ctx => …`.\n  const bareArrow = source.match(/^\\s*(?:async\\s+)?([A-Za-z_$][\\w$]*)\\s*=>/);\n\n  if (bareArrow) return [bareArrow[1]];\n\n  const openIndex = source.indexOf(\"(\");\n\n  if (openIndex === -1) return undefined;\n\n  return splitTopLevelParameters(source, openIndex);\n}\n\n/**\n * Whether a parameter is written as a destructuring pattern — `{ request }` or\n * `[a, b]` — as opposed to a plain name.\n */\nfunction isDestructured(parameter: string) {\n  const start = parameter.trimStart();\n\n  return start.startsWith(\"{\") || start.startsWith(\"[\");\n}\n\n/**\n * Does this handler look like it was written for the v4 positional signature?\n *\n * ## The signal, and what it misses\n *\n * `Function.length` alone is not enough, because it stops counting at the first\n * defaulted parameter:\n *\n * | handler                            | `.length` | actually |\n * | ---------------------------------- | --------- | -------- |\n * | `({ request, response }) => …`     | 1         | v5       |\n * | `(ctx) => …`                       | 1         | v5       |\n * | `(request, response) => …`         | 2         | v4       |\n * | `(request, response = x) => …`     | 1         | v4       |\n *\n * So the primary signal is the function's own source: a handler is suspect when\n * it declares **two or more** parameters and the first is **not** destructured.\n * Reading the source catches the defaulted row that arity cannot, and rules out\n * the `({ … }, extra)` shape that arity would wrongly flag.\n *\n * When the source is unreadable — a bound or native function — this falls back\n * to `handler.length >= 2`, which `bind` preserves. That is a weaker signal but\n * never a wrong one for the common cases; it only loses the defaulted row.\n *\n * ## What is still missed, by design\n *\n * A one-parameter v4 handler (`(request) => …`) is indistinguishable from a v5\n * `(ctx) => …` and is deliberately not flagged — guessing there would produce\n * false positives on correct code. False positives against the canonical\n * `({ … })` form are essentially nil, and every miss simply leaves today's\n * behaviour in place.\n */\nexport function looksLikePositionalHandler(handler: unknown): boolean {\n  if (typeof handler !== \"function\") return false;\n\n  const parameters = readParameterList(handler);\n\n  if (parameters) {\n    return parameters.length >= 2 && !isDestructured(parameters[0]);\n  }\n\n  return handler.length >= 2;\n}\n\n/**\n * The name to print for a handler.\n *\n * `Function.bind` prefixes the name with `\"bound \"`, and the router binds every\n * `[Controller, \"method\"]` tuple handler. The bare method name is what the user\n * actually wrote, so that is what gets printed.\n */\nfunction handlerDisplayName(handler: Function): string {\n  return handler.name?.replace(/^bound /, \"\").trim() || \"(anonymous)\";\n}\n\n/**\n * Inspect one route's handler as it registers, recording it when it looks like\n * the v4 positional form. Called from `Router.add`, so the cost is paid once per\n * route at registration and never per request.\n *\n * Deliberately total: any unexpected failure in the heuristic is swallowed, so a\n * diagnostic can never be the reason a route fails to register.\n */\nexport function inspectHandlerSignature(\n  handler: unknown,\n  route: { method: Route[\"method\"]; path: string; sourceFile: string },\n) {\n  try {\n    if (!looksLikePositionalHandler(handler)) return;\n\n    suspects.push({\n      method: route.method,\n      path: route.path,\n      handlerName: handlerDisplayName(handler as Function),\n      sourceFile: route.sourceFile,\n    });\n  } catch {\n    // A diagnostic must never break registration.\n  }\n}\n\n/**\n * Every suspect recorded so far, in registration order.\n */\nexport function listPositionalHandlerSuspects(): readonly PositionalHandlerSuspect[] {\n  return suspects;\n}\n\n/**\n * Drop the suspects belonging to a route file. Kept in step with\n * `Router.removeRoutesBySourceFile` so an HMR reload that fixes a handler does\n * not keep reporting the version it replaced.\n */\nexport function forgetPositionalHandlerSuspects(sourceFile: string) {\n  for (let index = suspects.length - 1; index >= 0; index--) {\n    if (suspects[index].sourceFile === sourceFile) {\n      suspects.splice(index, 1);\n    }\n  }\n}\n\n/**\n * Drop every recorded suspect. Intended for tests, which share the router\n * singleton.\n */\nexport function clearPositionalHandlerSuspects() {\n  suspects.length = 0;\n}\n\n/**\n * The one-line diagnostic for a single route. Written for someone who has never\n * read Warlock's internals: it names the handler, the route, what is wrong, and\n * the exact edit that fixes it.\n */\nexport function describePositionalHandlerSuspect(suspect: PositionalHandlerSuspect): string {\n  return (\n    `Handler \"${suspect.handlerName}\" (${suspect.method} ${suspect.path}) looks like ` +\n    `the v4 positional signature (request, response). ` +\n    `v5 passes a single context object — change it to ({ request, response }).`\n  );\n}\n\n/**\n * The full boot-time warning: every suspect, once, in one entry.\n *\n * One boot, one list — not one warning per route, and emphatically not one 500\n * per request. Returns the reported suspects so callers can assert on them.\n */\nexport function reportPositionalHandlerSuspects(logger: Pick<typeof log, \"warn\"> = log) {\n  const reported = [...suspects];\n\n  if (reported.length === 0) return reported;\n\n  const headline =\n    reported.length === 1\n      ? \"1 route handler looks like the v4 positional signature.\"\n      : `${reported.length} route handlers look like the v4 positional signature.`;\n\n  logger.warn({\n    module: \"router\",\n    action: \"handlerSignature\",\n    message:\n      `${headline} Warlock v5 calls every route handler with a single context object, ` +\n      `so a second parameter is always undefined and the request fails as soon as it is used:\\n` +\n      reported.map((suspect) => `  - ${describePositionalHandlerSuspect(suspect)}`).join(\"\\n\"),\n    context: { handlers: reported },\n  });\n\n  return reported;\n}\n"],"mappings":"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"}

package/esm/router/route-registry.d.mts

@@ -0,0 +1,34 @@
+import { Route } from "./types.mjs";
+
+//#region ../core/src/router/route-registry.d.ts
+/**
+ * Route Registry
+ * Manages dynamic route matching using find-my-way for HMR support
+ */
+declare class RouteRegistry {
+  private router;
+  constructor();
+  /**
+   * Register all routes from the router's internal list
+   */
+  register(routes: Route[]): void;
+  /**
+   * Register a single route
+   */
+  registerRoute(route: Route): void;
+  /**
+   * Find a matching route for the given method and URL
+   * @returns Matched route with extracted params, or null if no match
+   */
+  find(method: string, url: string): {
+    route: Route;
+    params: Record<string, string>;
+  } | null;
+  /**
+   * Get all registered routes count (for debugging)
+   */
+  getRouteCount(): number;
+}
+//#endregion
+export { RouteRegistry };
+//# sourceMappingURL=route-registry.d.mts.map

package/esm/router/route-registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-registry.d.mts","names":[],"sources":["../../../../../../../core/src/router/route-registry.ts"],"mappings":";;;;;AAsBA;;cAAa,aAAA;EAAA,QACH,MAAA;;EA6CI;;;EAjCL,QAAA,CAAS,MAAA,EAAQ,KAAA;EAZhB;;;EA+BD,aAAA,CAAc,KAAA,EAAO,KAAA;EAnBZ;;;;EA8BT,IAAA,CACL,MAAA,UACA,GAAA;IACG,KAAA,EAAO,KAAA;IAAO,MAAA,EAAQ,MAAA;EAAA;EAAf;;;EAkBL,aAAA;AAAA"}

package/esm/router/router.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.mts","names":[],"sources":["../../../../../../../core/src/router/router.ts"],"mappings":"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"}
+{"version":3,"file":"router.d.mts","names":[],"sources":["../../../../../../../core/src/router/router.ts"],"mappings":";;;;;;;cA4Ha,MAAA;;AAAb;;UAIU,MAAA;EAoBqB;;;;;;;;EAAA,QAVrB,aAAA;EAuDgD;;;EAAA,eAlDzC,QAAA;EAwHE;;;EAAA,UAnHP,iBAAA,EAAmB,oBAAA;EA4IlB;;;EAAA,UAvID,cAAA,EAAgB,MAAA,WAAiB,MAAA,EAAQ,MAAA,EAAQ,MAAA,EAAQ,eAAA;EAqPjC;;;;EAAA,UA9OxB,MAAA,EAAQ,YAAA;EA4P6C;;;EAAA,OAnPjD,WAAA,IAAW,MAAA;EAAA,QAQlB,WAAA;EAgQ4B;;;EAzP5B,cAAA,CAAe,QAAA,GAAW,MAAA,EAAQ,MAAA,EAAQ,MAAA,EAAQ,eAAA;EAuQrB;;;EA9P7B,aAAA,CAAc,QAAA,GAAW,MAAA,EAAQ,MAAA,EAAQ,MAAA,EAAQ,eAAA;EAgR7C;;;EAvQJ,QAAA,CAAS,IAAA,UAAc,EAAA,UAAY,YAAA;EAyQpB;;;EAhQf,SAAA,CAAU,OAAA,EAAS,oBAAA;EAuW4B;;;EA9V/C,IAAA,CAAK,IAAA,UAAc,QAAA,UAAkB,SAAA;EA+ajC;;;EAtaJ,UAAA,CAAW,IAAA,UAAc,QAAA,UAAkB,SAAA;EAgmBrB;;;EAvlBtB,KAAA,CAAM,KAAA,EAAO,MAAA,kBAAwB,SAAA;EApGpC;;;EA+GD,WAAA,CAAY,KAAA,EAAO,MAAA,kBAAwB,SAAA;EAhGxC;;;EA2GH,KAAA,CACL,IAAA,UACA,OAAA,UACA,OAAA,GAAU,IAAA,CAAK,uBAAA;EAEV,KAAA,CAAM,OAAA,EAAS,uBAAA;EAhHqC;;;EAoIpD,GAAA,CACL,MAAA,EAAQ,KAAA,YACR,IAAA,qBACA,OAAA,EAAS,kBAAA,EACT,OAAA,GAAS,YAAA;EAxHc;;;EA8NlB,GAAA,CAAI,IAAA,UAAc,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA/M9B;;;EAsN1B,GAAA,CAAI,IAAA,UAAc,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA7MxD;;;EAoNA,IAAA,CAAK,IAAA,qBAAyB,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EApN3B;;;EA2NzC,GAAA,CAAI,IAAA,UAAc,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EAlNjC;;;EAyNvB,MAAA,CAAO,IAAA,qBAAyB,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EAhN5D;;;EAuNV,KAAA,CAAM,IAAA,UAAc,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA9MrB;;;EAqNrC,IAAA,CAAK,IAAA,UAAc,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA5Md;;;EAmN3C,OAAA,CAAQ,IAAA,UAAc,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA1MvB;;;EAiNrC,KAAA,CAAM,IAAA,UAAc,OAAA,GAAS,YAAA,GAAiB,YAAA;EAtMH;;;;;;;;;;EAoN3C,eAAA,CACL,IAAA,UACA,QAAA,EAAU,aAAA,EACV,OAAA,GAAS,YAAA;IACP,IAAA,GAAO,cAAA;IACP,MAAA,GAAS,cAAA;IACT,OAAA,GAAU,OAAA,CAAQ,MAAA,CAAO,cAAA,EAAgB,cAAA;MACvC,UAAA,GAAa,cAAA;IAAA;EAAA;EAnLjB;;;EAyRK,KAAA,CAAM,OAAA,EAAS,oBAAA,EAAsB,QAAA,EAAU,mBAAA;EAnL7B;;;EAuOlB,MAAA,CAAO,MAAA,UAAgB,QAAA;EAhOnB;;;;;;;;;;;;EAgPJ,OAAA,CAAQ,OAAA,mBAA0B,QAAA;EAlOP;;;;;;EA4OrB,cAAA,UACX,UAAA,UACA,QAAA,QAAgB,CAAA,GAAI,OAAA,CAAQ,CAAA,IAC3B,OAAA,CAAQ,CAAA;EAxO4B;;;;;EAyQhC,wBAAA,CAAyB,UAAA;EAlQL;;;EAAA,QA+QnB,gBAAA;EAxQI;;;EAoVL,IAAA,IAAI,KAAA;EApV4C;;;;;;;;EAgWhD,UAAA;EAlV6B;;;EAyV7B,IAAA,CAAK,MAAA,EAAQ,eAAA;EA1UlB;;;;EAuXK,aAAA,CAAc,MAAA,EAAQ,eAAA;EApXlB;;;EA2eJ,QAAA,CAAS,IAAA,UAAc,MAAA;EAzehB;;;EAAA,QA8fN,WAAA;AAAA;AAAA,cA4CG,MAAA,EAAM,MAAuB"}