@warlock.js/core 5.30.0 → 5.32.0

package/esm/router/log-request-lifecycle.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"log-request-lifecycle.mjs","names":[],"sources":["../../../../../../../../packages/core/src/router/log-request-lifecycle.ts"],"sourcesContent":["/**\n * Both ends of a request's log entry.\n *\n * ## Why the completion line exists\n *\n * The router logged `Starting Request: <id>` and nothing else. A request that\n * hung for thirty seconds and one that returned in two milliseconds produced\n * **byte-identical output**, so the log could not answer the one question\n * anyone opens it to ask.\n *\n * Note what \"detecting a hang\" actually means. Nothing can log the completion\n * of a request that never completes — the mechanism is the **absence** of a\n * completion line beside a start line that has one. That only works if the\n * completion line is emitted on every settled path, **including a throw**,\n * which is why the error path here is not an afterthought.\n *\n * ## Why the level tracks the status\n *\n * A handled 500 does not throw; it returns a response. Logging it at `info`\n * would bury the exact entries someone scanning the log is hunting for, so the\n * level is derived from the outcome: informational below 400, a warning for\n * client errors, an error for server errors and for anything that threw.\n *\n * ## Ports rather than a direct `log` import\n *\n * The behaviour worth pinning down is *which lines come out, in which order,\n * at which level, when the run throws*. Injecting the sink and the clock makes\n * that assertable without a server, a socket or a fake timer.\n *\n * ## Tracing\n *\n * This function is the single funnel for both the success and throw paths\n * (the try/catch below), and it already reads the settled status via\n * `descriptor.statusCode()` after the run settles — the natural place to\n * fire `onRequestStart` / `onRequestEnd`, since that is when the response is\n * actually written and a trace can record what really happened. Gated on\n * `isTracingEnabled()` before building any context object, so a disabled app\n * pays one boolean check and allocates nothing extra.\n */\nimport type { Request } from \"../http/request\";\nimport { buildTracingContext, dispatchRequestEnd, dispatchRequestStart, isTracingEnabled } from \"../http/tracing\";\n\nexport type RequestLogEntry = {\n  module: string;\n  action: string;\n  message: string;\n  /**\n   * Typed as the logger accepts it, not as `unknown`. These entries exist to be\n   * handed to `log.info` / `warn` / `error`, whose parameter is\n   * `Record<string, any>` — `unknown` was not assignable, so the adapter in\n   * router.ts could not compile even though every real caller passes an object.\n   */\n  context?: Record<string, any>;\n};\n\nexport type RequestLogPorts = {\n  info(entry: RequestLogEntry): void;\n  warn(entry: RequestLogEntry): void;\n  error(entry: RequestLogEntry): void;\n  /** Monotonic milliseconds. Called exactly twice per request. */\n  now(): number;\n};\n\nexport type RequestLogDescriptor = {\n  module: string;\n  action: string;\n  requestId: string;\n  /**\n   * Typed as the logger accepts it, not as `unknown`. These entries exist to be\n   * handed to `log.info` / `warn` / `error`, whose parameter is\n   * `Record<string, any>` — `unknown` was not assignable, so the adapter in\n   * router.ts could not compile even though every real caller passes an object.\n   */\n  context?: Record<string, any>;\n  /**\n   * Read AFTER the run settles — the status is decided during the request, so\n   * capturing it up front would report the default on every entry.\n   */\n  statusCode(): number | undefined;\n  /**\n   * The `Request` instance, when tracing needs it to build\n   * the `TracingContext` for `onRequestStart` / `onRequestEnd`. Optional —\n   * absent, tracing dispatch for this request is skipped, which is correct\n   * for any non-HTTP caller of this same lifecycle wrapper.\n   */\n  request?: Request;\n};\n\ntype Level = \"info\" | \"warn\" | \"error\";\n\nfunction levelForStatus(statusCode: number | undefined): Level {\n  // An unknown status is not evidence of a problem; saying \"error\" because we\n  // failed to read a number would be inventing a defect.\n  if (statusCode === undefined) return \"info\";\n\n  if (statusCode >= 500) return \"error\";\n\n  if (statusCode >= 400) return \"warn\";\n\n  return \"info\";\n}\n\nexport async function logRequestLifecycle<TResult>(\n  ports: RequestLogPorts,\n  descriptor: RequestLogDescriptor,\n  run: () => Promise<TResult>,\n): Promise<TResult> {\n  const startedAt = ports.now();\n  const tracingEnabled = isTracingEnabled();\n\n  ports.info({\n    module: descriptor.module,\n    action: descriptor.action,\n    message: `Starting Request: ${descriptor.requestId}`,\n    context: descriptor.context,\n  });\n\n  if (tracingEnabled && descriptor.request) {\n    dispatchRequestStart(buildTracingContext(descriptor.request));\n  }\n\n  const finish = (level: Level, outcome: string, error?: unknown): void => {\n    const duration = Math.round(ports.now() - startedAt);\n\n    ports[level]({\n      module: descriptor.module,\n      action: descriptor.action,\n      message: `Completed Request: ${descriptor.requestId} — ${outcome} in ${duration}ms`,\n      context: descriptor.context,\n    });\n\n    if (tracingEnabled && descriptor.request) {\n      dispatchRequestEnd(buildTracingContext(descriptor.request), {\n        status: descriptor.statusCode(),\n        durationMs: duration,\n        error,\n      });\n    }\n  };\n\n  try {\n    const result = await run();\n\n    const statusCode = descriptor.statusCode();\n\n    finish(levelForStatus(statusCode), statusCode === undefined ? \"no status\" : String(statusCode));\n\n    return result;\n  } catch (error) {\n    // The throw is reported and then re-thrown untouched: this function\n    // observes the request, it does not own its error handling.\n    finish(\"error\", `threw ${error instanceof Error ? error.name : typeof error}`, error);\n\n    throw error;\n  }\n}\n"],"mappings":";;;;AA0FA,SAAS,eAAe,YAAuC;CAG7D,IAAI,eAAe,QAAW,OAAO;CAErC,IAAI,cAAc,KAAK,OAAO;CAE9B,IAAI,cAAc,KAAK,OAAO;CAE9B,OAAO;AACT;AAEA,eAAsB,oBACpB,OACA,YACA,KACkB;CAClB,MAAM,YAAY,MAAM,IAAI;CAC5B,MAAM,iBAAiB,iBAAiB;CAExC,MAAM,KAAK;EACT,QAAQ,WAAW;EACnB,QAAQ,WAAW;EACnB,SAAS,qBAAqB,WAAW;EACzC,SAAS,WAAW;CACtB,CAAC;CAED,IAAI,kBAAkB,WAAW,SAC/B,qBAAqB,oBAAoB,WAAW,OAAO,CAAC;CAG9D,MAAM,UAAU,OAAc,SAAiB,UAA0B;EACvE,MAAM,WAAW,KAAK,MAAM,MAAM,IAAI,IAAI,SAAS;EAEnD,MAAM,MAAM,CAAC;GACX,QAAQ,WAAW;GACnB,QAAQ,WAAW;GACnB,SAAS,sBAAsB,WAAW,UAAU,KAAK,QAAQ,MAAM,SAAS;GAChF,SAAS,WAAW;EACtB,CAAC;EAED,IAAI,kBAAkB,WAAW,SAC/B,mBAAmB,oBAAoB,WAAW,OAAO,GAAG;GAC1D,QAAQ,WAAW,WAAW;GAC9B,YAAY;GACZ;EACF,CAAC;CAEL;CAEA,IAAI;EACF,MAAM,SAAS,MAAM,IAAI;EAEzB,MAAM,aAAa,WAAW,WAAW;EAEzC,OAAO,eAAe,UAAU,GAAG,eAAe,SAAY,cAAc,OAAO,UAAU,CAAC;EAE9F,OAAO;CACT,SAAS,OAAO;EAGd,OAAO,SAAS,SAAS,iBAAiB,QAAQ,MAAM,OAAO,OAAO,SAAS,KAAK;EAEpF,MAAM;CACR;AACF"}
+{"version":3,"file":"log-request-lifecycle.mjs","names":[],"sources":["../../../../../../../../packages/core/src/router/log-request-lifecycle.ts"],"sourcesContent":["/**\n * Both ends of a request's log entry.\n *\n * ## Why the completion line exists\n *\n * The router logged `Starting Request: <id>` and nothing else. A request that\n * hung for thirty seconds and one that returned in two milliseconds produced\n * **byte-identical output**, so the log could not answer the one question\n * anyone opens it to ask.\n *\n * Note what \"detecting a hang\" actually means. Nothing can log the completion\n * of a request that never completes — the mechanism is the **absence** of a\n * completion line beside a start line that has one. That only works if the\n * completion line is emitted on every settled path, **including a throw**,\n * which is why the error path here is not an afterthought.\n *\n * ## Why the level tracks the status\n *\n * A handled 500 does not throw; it returns a response. Logging it at `info`\n * would bury the exact entries someone scanning the log is hunting for, so the\n * level is derived from the outcome: informational below 400, a warning for\n * client errors, an error for server errors and for anything that threw.\n *\n * ## Ports rather than a direct `log` import\n *\n * The behaviour worth pinning down is *which lines come out, in which order,\n * at which level, when the run throws*. Injecting the sink and the clock makes\n * that assertable without a server, a socket or a fake timer.\n *\n * ## Tracing\n *\n * This function is the single funnel for both the success and throw paths\n * (the try/catch below), and it already reads the settled status via\n * `descriptor.statusCode()` after the run settles — the natural place to\n * fire `onRequestStart` / `onRequestEnd`, since that is when the response is\n * actually written and a trace can record what really happened. Gated on\n * `isTracingEnabled()` before building any context object, so a disabled app\n * pays one boolean check and allocates nothing extra.\n */\nimport type { Request } from \"../http/request\";\nimport {\n  buildTracingContext,\n  dispatchRequestEnd,\n  dispatchRequestStart,\n  isTracingEnabled,\n} from \"../http/tracing\";\n\nexport type RequestLogEntry = {\n  module: string;\n  action: string;\n  message: string;\n  /**\n   * Typed as the logger accepts it, not as `unknown`. These entries exist to be\n   * handed to `log.info` / `warn` / `error`, whose parameter is\n   * `Record<string, any>` — `unknown` was not assignable, so the adapter in\n   * router.ts could not compile even though every real caller passes an object.\n   */\n  context?: Record<string, any>;\n};\n\nexport type RequestLogPorts = {\n  info(entry: RequestLogEntry): void;\n  warn(entry: RequestLogEntry): void;\n  error(entry: RequestLogEntry): void;\n  /** Monotonic milliseconds. Called exactly twice per request. */\n  now(): number;\n};\n\nexport type RequestLogDescriptor = {\n  module: string;\n  action: string;\n  requestId: string;\n  /**\n   * Typed as the logger accepts it, not as `unknown`. These entries exist to be\n   * handed to `log.info` / `warn` / `error`, whose parameter is\n   * `Record<string, any>` — `unknown` was not assignable, so the adapter in\n   * router.ts could not compile even though every real caller passes an object.\n   */\n  context?: Record<string, any>;\n  /**\n   * Read AFTER the run settles — the status is decided during the request, so\n   * capturing it up front would report the default on every entry.\n   */\n  statusCode(): number | undefined;\n  /**\n   * The `Request` instance, when tracing needs it to build\n   * the `TracingContext` for `onRequestStart` / `onRequestEnd`. Optional —\n   * absent, tracing dispatch for this request is skipped, which is correct\n   * for any non-HTTP caller of this same lifecycle wrapper.\n   */\n  request?: Request;\n};\n\ntype Level = \"info\" | \"warn\" | \"error\";\n\nfunction levelForStatus(statusCode: number | undefined): Level {\n  // An unknown status is not evidence of a problem; saying \"error\" because we\n  // failed to read a number would be inventing a defect.\n  if (statusCode === undefined) return \"info\";\n\n  if (statusCode >= 500) return \"error\";\n\n  if (statusCode >= 400) return \"warn\";\n\n  return \"info\";\n}\n\nexport async function logRequestLifecycle<TResult>(\n  ports: RequestLogPorts,\n  descriptor: RequestLogDescriptor,\n  run: () => Promise<TResult>,\n): Promise<TResult> {\n  const startedAt = ports.now();\n  const tracingEnabled = isTracingEnabled();\n\n  ports.info({\n    module: descriptor.module,\n    action: descriptor.action,\n    message: `Starting Request: ${descriptor.requestId}`,\n    context: descriptor.context,\n  });\n\n  if (tracingEnabled && descriptor.request) {\n    dispatchRequestStart(buildTracingContext(descriptor.request));\n  }\n\n  const finish = (level: Level, outcome: string, error?: unknown): void => {\n    const duration = Math.round(ports.now() - startedAt);\n\n    ports[level]({\n      module: descriptor.module,\n      action: descriptor.action,\n      message: `Completed Request: ${descriptor.requestId} — ${outcome} in ${duration}ms`,\n      context: descriptor.context,\n    });\n\n    if (tracingEnabled && descriptor.request) {\n      dispatchRequestEnd(buildTracingContext(descriptor.request), {\n        status: descriptor.statusCode(),\n        durationMs: duration,\n        error,\n      });\n    }\n  };\n\n  try {\n    const result = await run();\n\n    const statusCode = descriptor.statusCode();\n\n    finish(levelForStatus(statusCode), statusCode === undefined ? \"no status\" : String(statusCode));\n\n    return result;\n  } catch (error) {\n    // The throw is reported and then re-thrown untouched: this function\n    // observes the request, it does not own its error handling.\n    finish(\"error\", `threw ${error instanceof Error ? error.name : typeof error}`, error);\n\n    throw error;\n  }\n}\n"],"mappings":";;;;AA+FA,SAAS,eAAe,YAAuC;CAG7D,IAAI,eAAe,QAAW,OAAO;CAErC,IAAI,cAAc,KAAK,OAAO;CAE9B,IAAI,cAAc,KAAK,OAAO;CAE9B,OAAO;AACT;AAEA,eAAsB,oBACpB,OACA,YACA,KACkB;CAClB,MAAM,YAAY,MAAM,IAAI;CAC5B,MAAM,iBAAiB,iBAAiB;CAExC,MAAM,KAAK;EACT,QAAQ,WAAW;EACnB,QAAQ,WAAW;EACnB,SAAS,qBAAqB,WAAW;EACzC,SAAS,WAAW;CACtB,CAAC;CAED,IAAI,kBAAkB,WAAW,SAC/B,qBAAqB,oBAAoB,WAAW,OAAO,CAAC;CAG9D,MAAM,UAAU,OAAc,SAAiB,UAA0B;EACvE,MAAM,WAAW,KAAK,MAAM,MAAM,IAAI,IAAI,SAAS;EAEnD,MAAM,MAAM,CAAC;GACX,QAAQ,WAAW;GACnB,QAAQ,WAAW;GACnB,SAAS,sBAAsB,WAAW,UAAU,KAAK,QAAQ,MAAM,SAAS;GAChF,SAAS,WAAW;EACtB,CAAC;EAED,IAAI,kBAAkB,WAAW,SAC/B,mBAAmB,oBAAoB,WAAW,OAAO,GAAG;GAC1D,QAAQ,WAAW,WAAW;GAC9B,YAAY;GACZ;EACF,CAAC;CAEL;CAEA,IAAI;EACF,MAAM,SAAS,MAAM,IAAI;EAEzB,MAAM,aAAa,WAAW,WAAW;EAEzC,OAAO,eAAe,UAAU,GAAG,eAAe,SAAY,cAAc,OAAO,UAAU,CAAC;EAE9F,OAAO;CACT,SAAS,OAAO;EAGd,OAAO,SAAS,SAAS,iBAAiB,QAAQ,MAAM,OAAO,OAAO,SAAS,KAAK;EAEpF,MAAM;CACR;AACF"}

package/esm/router/named-api-routes-with-responses.mjs

@@ -30,7 +30,8 @@ async function importResourceNamespaces(files, onWarn) {
 * cannot be imported is reported once through `onWarn` and left out of the map.
 */
 async function collectResourceExportMap(files, onWarn) {
-	return buildResourceMap(await importResourceNamespaces([...files].filter(isResourceFile), onWarn));
+	const namespaces = await importResourceNamespaces([...files].filter(isResourceFile), onWarn);
+	return buildResourceMap(namespaces);
 }
 /**
 * Named API route snapshots, with a `response` type map on every route whose handler

package/esm/router/named-api-routes-with-responses.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"named-api-routes-with-responses.mjs","names":[],"sources":["../../../../../../../../packages/core/src/router/named-api-routes-with-responses.ts"],"sourcesContent":["import { pathToFileURL } from \"node:url\";\nimport { importAppModule } from \"../loader/app-module-importer\";\nimport {\n  buildResourceMap,\n  createResourceTypeResolver,\n  describeResponseSchemaTypes,\n  type ResourceModuleExport,\n  type ResourceModuleNamespace,\n  type ResourceTypeResolver,\n} from \"./response-schema-types\";\nimport { router } from \"./router\";\nimport type { NamedApiRoute } from \"./types\";\n\nconst RESOURCE_FILE_PATTERN = /(^|\\/)src\\/.*\\.resource\\.tsx?$/;\n\nexport type ResourceSourceFile = Readonly<{\n  absolutePath: string;\n  relativePath: string;\n}>;\n\nexport type NamedApiRoutesWithResponsesOptions = Readonly<{\n  /**\n   * Application root, the folder that contains `.warlock/typings/`.\n   */\n  appRoot: string;\n  /**\n   * Every file the orchestrator knows about. `*.resource.ts(x)` files under `src/` are\n   * imported to map resource classes back to their exports.\n   */\n  files: Iterable<ResourceSourceFile>;\n  /**\n   * Receives a human readable warning (unmapped resource, unreadable resource module).\n   */\n  onWarn?: (message: string) => void;\n}>;\n\nfunction isResourceFile(file: ResourceSourceFile): boolean {\n  return RESOURCE_FILE_PATTERN.test(file.relativePath.replace(/\\\\/g, \"/\"));\n}\n\nasync function importResourceNamespaces(\n  files: readonly ResourceSourceFile[],\n  onWarn: ((message: string) => void) | undefined,\n): Promise<ResourceModuleNamespace[]> {\n  const namespaces: ResourceModuleNamespace[] = [];\n\n  for (const file of files) {\n    try {\n      const namespace = (await importAppModule(pathToFileURL(file.absolutePath).href)) as Record<\n        string,\n        unknown\n      >;\n\n      namespaces.push({ file: file.absolutePath, namespace });\n    } catch (error) {\n      onWarn?.(\n        `Could not import ${file.relativePath} to type API responses: ${\n          error instanceof Error ? error.message : String(error)\n        }`,\n      );\n    }\n  }\n\n  return namespaces;\n}\n\n/**\n * Identity map from every resource class exported by a `*.resource.ts(x)` file under\n * `src/` to the module export it came from.\n *\n * The modules are imported through the same importer the routes used, so a resource class\n * found in a `responseSchema` is the very instance exported by its module. A module that\n * cannot be imported is reported once through `onWarn` and left out of the map.\n */\nexport async function collectResourceExportMap(\n  files: Iterable<ResourceSourceFile>,\n  onWarn?: (message: string) => void,\n): Promise<Map<unknown, ResourceModuleExport>> {\n  const namespaces = await importResourceNamespaces([...files].filter(isResourceFile), onWarn);\n\n  return buildResourceMap(namespaces);\n}\n\n/**\n * Named API route snapshots, with a `response` type map on every route whose handler\n * declares `responseSchema`.\n *\n * Resource modules are imported only when at least one route declares a schema, through\n * the same importer the routes used, so a resource class seen in a schema is the very\n * instance exported by its module. Never throws: if anything fails the routes come back\n * without `response` (and the failure is reported once through `onWarn`).\n */\nexport async function collectNamedApiRoutesWithResponses(\n  options: NamedApiRoutesWithResponsesOptions,\n): Promise<readonly NamedApiRoute[]> {\n  try {\n    const declaresSchema = router.list().some((route) => route.handler?.responseSchema);\n\n    if (!declaresSchema) return router.getNamedApiRoutes();\n\n    const resolveResource: ResourceTypeResolver = createResourceTypeResolver(\n      await collectResourceExportMap(options.files, options.onWarn),\n      options.appRoot,\n    );\n\n    return router.getNamedApiRoutes({\n      resolveResponse: (schema, route) =>\n        describeResponseSchemaTypes(schema, resolveResource, (fieldPath) => {\n          options.onWarn?.(\n            `Route \"${route.name}\" (${route.method} ${route.path}): response ${fieldPath} is a resource that is not exported from a *.resource.ts file, typed as unknown.`,\n          );\n        }),\n    });\n  } catch (error) {\n    options.onWarn?.(\n      `Could not type API responses: ${error instanceof Error ? error.message : String(error)}`,\n    );\n\n    return router.getNamedApiRoutes();\n  }\n}\n"],"mappings":";;;;;;AAaA,MAAM,wBAAwB;AAuB9B,SAAS,eAAe,MAAmC;CACzD,OAAO,sBAAsB,KAAK,KAAK,aAAa,QAAQ,OAAO,GAAG,CAAC;AACzE;AAEA,eAAe,yBACb,OACA,QACoC;CACpC,MAAM,aAAwC,CAAC;CAE/C,KAAK,MAAM,QAAQ,OACjB,IAAI;EACF,MAAM,YAAa,MAAM,gBAAgB,cAAc,KAAK,YAAY,CAAC,CAAC,IAAI;EAK9E,WAAW,KAAK;GAAE,MAAM,KAAK;GAAc;EAAU,CAAC;CACxD,SAAS,OAAO;EACd,SACE,oBAAoB,KAAK,aAAa,0BACpC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAEzD;CACF;CAGF,OAAO;AACT;;;;;;;;;AAUA,eAAsB,yBACpB,OACA,QAC6C;CAG7C,OAAO,iBAAiB,MAFC,yBAAyB,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,cAAc,GAAG,MAAM,CAEzD;AACpC;;;;;;;;;;AAWA,eAAsB,mCACpB,SACmC;CACnC,IAAI;EAGF,IAAI,CAFmB,OAAO,KAAK,CAAC,CAAC,MAAM,UAAU,MAAM,SAAS,cAElD,GAAG,OAAO,OAAO,kBAAkB;EAErD,MAAM,kBAAwC,2BAC5C,MAAM,yBAAyB,QAAQ,OAAO,QAAQ,MAAM,GAC5D,QAAQ,OACV;EAEA,OAAO,OAAO,kBAAkB,EAC9B,kBAAkB,QAAQ,UACxB,4BAA4B,QAAQ,kBAAkB,cAAc;GAClE,QAAQ,SACN,UAAU,MAAM,KAAK,KAAK,MAAM,OAAO,GAAG,MAAM,KAAK,cAAc,UAAU,iFAC/E;EACF,CAAC,EACL,CAAC;CACH,SAAS,OAAO;EACd,QAAQ,SACN,iCAAiC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GACxF;EAEA,OAAO,OAAO,kBAAkB;CAClC;AACF"}
+{"version":3,"file":"named-api-routes-with-responses.mjs","names":[],"sources":["../../../../../../../../packages/core/src/router/named-api-routes-with-responses.ts"],"sourcesContent":["import { pathToFileURL } from \"node:url\";\nimport { importAppModule } from \"../loader/app-module-importer\";\nimport {\n  buildResourceMap,\n  createResourceTypeResolver,\n  describeResponseSchemaTypes,\n  type ResourceModuleExport,\n  type ResourceModuleNamespace,\n  type ResourceTypeResolver,\n} from \"./response-schema-types\";\nimport { router } from \"./router\";\nimport type { NamedApiRoute } from \"./types\";\n\nconst RESOURCE_FILE_PATTERN = /(^|\\/)src\\/.*\\.resource\\.tsx?$/;\n\nexport type ResourceSourceFile = Readonly<{\n  absolutePath: string;\n  relativePath: string;\n}>;\n\nexport type NamedApiRoutesWithResponsesOptions = Readonly<{\n  /**\n   * Application root, the folder that contains `.warlock/typings/`.\n   */\n  appRoot: string;\n  /**\n   * Every file the orchestrator knows about. `*.resource.ts(x)` files under `src/` are\n   * imported to map resource classes back to their exports.\n   */\n  files: Iterable<ResourceSourceFile>;\n  /**\n   * Receives a human readable warning (unmapped resource, unreadable resource module).\n   */\n  onWarn?: (message: string) => void;\n}>;\n\nfunction isResourceFile(file: ResourceSourceFile): boolean {\n  return RESOURCE_FILE_PATTERN.test(file.relativePath.replace(/\\\\/g, \"/\"));\n}\n\nasync function importResourceNamespaces(\n  files: readonly ResourceSourceFile[],\n  onWarn: ((message: string) => void) | undefined,\n): Promise<ResourceModuleNamespace[]> {\n  const namespaces: ResourceModuleNamespace[] = [];\n\n  for (const file of files) {\n    try {\n      const namespace = (await importAppModule(pathToFileURL(file.absolutePath).href)) as Record<\n        string,\n        unknown\n      >;\n\n      namespaces.push({ file: file.absolutePath, namespace });\n    } catch (error) {\n      onWarn?.(\n        `Could not import ${file.relativePath} to type API responses: ${\n          error instanceof Error ? error.message : String(error)\n        }`,\n      );\n    }\n  }\n\n  return namespaces;\n}\n\n/**\n * Identity map from every resource class exported by a `*.resource.ts(x)` file under\n * `src/` to the module export it came from.\n *\n * The modules are imported through the same importer the routes used, so a resource class\n * found in a `responseSchema` is the very instance exported by its module. A module that\n * cannot be imported is reported once through `onWarn` and left out of the map.\n */\nexport async function collectResourceExportMap(\n  files: Iterable<ResourceSourceFile>,\n  onWarn?: (message: string) => void,\n): Promise<Map<unknown, ResourceModuleExport>> {\n  const namespaces = await importResourceNamespaces([...files].filter(isResourceFile), onWarn);\n\n  return buildResourceMap(namespaces);\n}\n\n/**\n * Named API route snapshots, with a `response` type map on every route whose handler\n * declares `responseSchema`.\n *\n * Resource modules are imported only when at least one route declares a schema, through\n * the same importer the routes used, so a resource class seen in a schema is the very\n * instance exported by its module. Never throws: if anything fails the routes come back\n * without `response` (and the failure is reported once through `onWarn`).\n */\nexport async function collectNamedApiRoutesWithResponses(\n  options: NamedApiRoutesWithResponsesOptions,\n): Promise<readonly NamedApiRoute[]> {\n  try {\n    const declaresSchema = router.list().some((route) => route.handler?.responseSchema);\n\n    if (!declaresSchema) return router.getNamedApiRoutes();\n\n    const resolveResource: ResourceTypeResolver = createResourceTypeResolver(\n      await collectResourceExportMap(options.files, options.onWarn),\n      options.appRoot,\n    );\n\n    return router.getNamedApiRoutes({\n      resolveResponse: (schema, route) =>\n        describeResponseSchemaTypes(schema, resolveResource, (fieldPath) => {\n          options.onWarn?.(\n            `Route \"${route.name}\" (${route.method} ${route.path}): response ${fieldPath} is a resource that is not exported from a *.resource.ts file, typed as unknown.`,\n          );\n        }),\n    });\n  } catch (error) {\n    options.onWarn?.(\n      `Could not type API responses: ${error instanceof Error ? error.message : String(error)}`,\n    );\n\n    return router.getNamedApiRoutes();\n  }\n}\n"],"mappings":";;;;;;AAaA,MAAM,wBAAwB;AAuB9B,SAAS,eAAe,MAAmC;CACzD,OAAO,sBAAsB,KAAK,KAAK,aAAa,QAAQ,OAAO,GAAG,CAAC;AACzE;AAEA,eAAe,yBACb,OACA,QACoC;CACpC,MAAM,aAAwC,CAAC;CAE/C,KAAK,MAAM,QAAQ,OACjB,IAAI;EACF,MAAM,YAAa,MAAM,gBAAgB,cAAc,KAAK,YAAY,CAAC,CAAC,IAAI;EAK9E,WAAW,KAAK;GAAE,MAAM,KAAK;GAAc;EAAU,CAAC;CACxD,SAAS,OAAO;EACd,SACE,oBAAoB,KAAK,aAAa,0BACpC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GAEzD;CACF;CAGF,OAAO;AACT;;;;;;;;;AAUA,eAAsB,yBACpB,OACA,QAC6C;CAC7C,MAAM,aAAa,MAAM,yBAAyB,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,cAAc,GAAG,MAAM;CAE3F,OAAO,iBAAiB,UAAU;AACpC;;;;;;;;;;AAWA,eAAsB,mCACpB,SACmC;CACnC,IAAI;EAGF,IAAI,CAFmB,OAAO,KAAK,CAAC,CAAC,MAAM,UAAU,MAAM,SAAS,cAElD,GAAG,OAAO,OAAO,kBAAkB;EAErD,MAAM,kBAAwC,2BAC5C,MAAM,yBAAyB,QAAQ,OAAO,QAAQ,MAAM,GAC5D,QAAQ,OACV;EAEA,OAAO,OAAO,kBAAkB,EAC9B,kBAAkB,QAAQ,UACxB,4BAA4B,QAAQ,kBAAkB,cAAc;GAClE,QAAQ,SACN,UAAU,MAAM,KAAK,KAAK,MAAM,OAAO,GAAG,MAAM,KAAK,cAAc,UAAU,iFAC/E;EACF,CAAC,EACL,CAAC;CACH,SAAS,OAAO;EACd,QAAQ,SACN,iCAAiC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,GACxF;EAEA,OAAO,OAAO,kBAAkB;CAClC;AACF"}

package/esm/router/normalize-request-path.d.mts

@@ -8,7 +8,6 @@
  * slash optional. The root path is already canonical and must never become an
  * empty string.
  */
-declare function normalizeRequestPath(pathname: string): string;
+export declare function normalizeRequestPath(pathname: string): string;
 //#endregion
-export { normalizeRequestPath };
 //# sourceMappingURL=normalize-request-path.d.mts.map

package/esm/router/normalize-request-path.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-request-path.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/normalize-request-path.ts"],"mappings":";;AASA;;;;AAAqD;;;;iBAArC,oBAAA,CAAqB,QAAgB"}
+{"version":3,"file":"normalize-request-path.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/normalize-request-path.ts"],"mappings":";;;;;;;;;;wBASgB,qBAAqB"}

package/esm/router/normalize-route-path.d.mts

@@ -22,7 +22,6 @@
  * @example normalizeRoutePath("/users/", "/:id") // "/users/:id"
  * @example normalizeRoutePath("") // "/"
  */
-declare function normalizeRoutePath(...segments: string[]): string;
+export declare function normalizeRoutePath(...segments: string[]): string;
 //#endregion
-export { normalizeRoutePath };
 //# sourceMappingURL=normalize-route-path.d.mts.map

package/esm/router/normalize-route-path.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-route-path.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/normalize-route-path.ts"],"mappings":";;AAyBA;;;;AAA8C;;;;;;;;;;;;;;;;;;iBAA9B,kBAAA,IAAsB,QAAQ"}
+{"version":3,"file":"normalize-route-path.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/normalize-route-path.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;wBAyBgB,sBAAsB"}

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

@@ -1,14 +1,17 @@
 import { Route } from "./types.mjs";
 import { log } from "@warlock.js/logger";
-
 //#region ../../packages/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. */
+export 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;
 };
 /**
@@ -43,7 +46,7 @@ type PositionalHandlerSuspect = {
  * `({ … })` form are essentially nil, and every miss simply leaves today's
  * behaviour in place.
  */
-declare function looksLikePositionalHandler(handler: unknown): boolean;
+export 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
@@ -52,7 +55,7 @@ declare function looksLikePositionalHandler(handler: unknown): boolean;
  * 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: {
+export declare function inspectHandlerSignature(handler: unknown, route: {
   method: Route["method"];
   path: string;
   sourceFile: string;
@@ -60,31 +63,30 @@ declare function inspectHandlerSignature(handler: unknown, route: {
 /**
  * Every suspect recorded so far, in registration order.
  */
-declare function listPositionalHandlerSuspects(): readonly PositionalHandlerSuspect[];
+export 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;
+export declare function forgetPositionalHandlerSuspects(sourceFile: string): void;
 /**
  * Drop every recorded suspect. Intended for tests, which share the router
  * singleton.
  */
-declare function clearPositionalHandlerSuspects(): void;
+export 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;
+export 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[];
+export 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

@@ -1 +1 @@
-{"version":3,"file":"positional-handler-diagnostics.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/positional-handler-diagnostics.ts"],"mappings":";;;;AA+PsE;AAmBtE;;AAnBsE,KA3N1D,wBAAA;EA8OsE,kDA5OhF,MAAA,EAAQ,KAAK,YAqPC;EAlPd,IAAA;EAGA,WAAA,UA+OgE;EA5OhE,UAAA;AAAA;;;AA0P4C;AAS9C;;;;AAAkF;AAclF;;;;;;;;;;;;;AAAsF;;;;;;;;;;;iBApGtE,0BAAA,CAA2B,OAAgB;;;;;;;;;iBAiC3C,uBAAA,CACd,OAAA,WACA,KAAA;EAAS,MAAA,EAAQ,KAAK;EAAY,IAAA;EAAc,UAAA;AAAA;;;;iBAmBlC,6BAAA,aAA0C,wBAAwB;;;;;;iBASlE,+BAAA,CAAgC,UAAkB;;;;;iBAclD,8BAAA;;;;;;iBASA,gCAAA,CAAiC,OAAiC,EAAxB,wBAAwB;;;;;;;iBAclE,+BAAA,CAAgC,MAAA,GAAQ,IAAA,QAAY,GAAA,YAAkB,wBAAA"}
+{"version":3,"file":"positional-handler-diagnostics.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/positional-handler-diagnostics.ts"],"mappings":";;;;;;YAoCY;;EAEV,QAAQ;;EAGR;;EAGA;;EAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA6Kc,2BAA2B;;;;;;;;;wBAmC3B,wBACd,kBACA;EAAS,QAAQ;EAAiB;EAAc;;;;;wBAmBlC,0CAA0C;;;;;;wBAS1C,gCAAgC;;;;;wBAchC;;;;;;wBASA,iCAAiC,SAAS;;;;;;;wBAc1C,gCAAgC,SAAQ,YAAY,eAAkB"}

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

@@ -1 +1 @@
-{"version":3,"file":"positional-handler-diagnostics.mjs","names":[],"sources":["../../../../../../../../packages/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) {\n    const parameter = bareArrow[1];\n\n    return parameter === undefined ? undefined : [parameter];\n  }\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    const firstParameter = parameters[0];\n\n    return parameters.length >= 2 && firstParameter !== undefined && !isDestructured(firstParameter);\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    const suspect = suspects[index];\n\n    if (suspect?.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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,MAAM,WAAuC,CAAC;;;;;;;;;;;AAY9C,SAAS,wBAAwB,QAAgB,WAAyC;CACxF,MAAM,aAAuB,CAAC;CAE9B,IAAI,QAAQ;CACZ,IAAI,UAAU;CACd,IAAI,QAAQ;CAEZ,KAAK,IAAI,QAAQ,WAAW,QAAQ,OAAO,QAAQ,SAAS;EAC1D,MAAM,OAAO,OAAO;EAEpB,IAAI,OAAO;GACT,IAAI,SAAS,MAAM;IACjB,WAAW,QAAQ,OAAO,QAAQ,MAAM;IACxC;IACA;GACF;GAEA,IAAI,SAAS,OACX,QAAQ;GAGV,WAAW;GACX;EACF;EAEA,IAAI,SAAS,QAAO,SAAS,OAAO,SAAS,KAAK;GAChD,QAAQ;GACR,WAAW;GACX;EACF;EAEA,IAAI,SAAS,OAAO,SAAS,OAAO,SAAS,KAAK;GAChD;GAGA,IAAI,UAAU,GAAG;GAEjB,WAAW;GACX;EACF;EAEA,IAAI,SAAS,OAAO,SAAS,OAAO,SAAS,KAAK;GAChD;GAEA,IAAI,UAAU,GAAG;IACf,IAAI,QAAQ,KAAK,GACf,WAAW,KAAK,QAAQ,KAAK,CAAC;IAGhC,OAAO;GACT;GAEA,WAAW;GACX;EACF;EAEA,IAAI,SAAS,OAAO,UAAU,GAAG;GAC/B,WAAW,KAAK,QAAQ,KAAK,CAAC;GAC9B,UAAU;GACV;EACF;EAEA,WAAW;CACb;AAIF;;;;;;;;;;;;;;AAeA,SAAS,kBAAkB,SAAyC;CAClE,IAAI;CAEJ,IAAI;EACF,SAAS,SAAS,UAAU,SAAS,KAAK,OAAO;CACnD,QAAQ;EACN;CACF;CAEA,IAAI,OAAO,SAAS,eAAe,GAAG,OAAO;CAE7C,IAAI,iBAAiB,KAAK,MAAM,GAAG,OAAO;CAG1C,MAAM,YAAY,OAAO,MAAM,0CAA0C;CAEzE,IAAI,WAAW;EACb,MAAM,YAAY,UAAU;EAE5B,OAAO,cAAc,SAAY,SAAY,CAAC,SAAS;CACzD;CAEA,MAAM,YAAY,OAAO,QAAQ,GAAG;CAEpC,IAAI,cAAc,IAAI,OAAO;CAE7B,OAAO,wBAAwB,QAAQ,SAAS;AAClD;;;;;AAMA,SAAS,eAAe,WAAmB;CACzC,MAAM,QAAQ,UAAU,UAAU;CAElC,OAAO,MAAM,WAAW,GAAG,KAAK,MAAM,WAAW,GAAG;AACtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,SAAgB,2BAA2B,SAA2B;CACpE,IAAI,OAAO,YAAY,YAAY,OAAO;CAE1C,MAAM,aAAa,kBAAkB,OAAO;CAE5C,IAAI,YAAY;EACd,MAAM,iBAAiB,WAAW;EAElC,OAAO,WAAW,UAAU,KAAK,mBAAmB,UAAa,CAAC,eAAe,cAAc;CACjG;CAEA,OAAO,QAAQ,UAAU;AAC3B;;;;;;;;AASA,SAAS,mBAAmB,SAA2B;CACrD,OAAO,QAAQ,MAAM,QAAQ,WAAW,EAAE,CAAC,CAAC,KAAK,KAAK;AACxD;;;;;;;;;AAUA,SAAgB,wBACd,SACA,OACA;CACA,IAAI;EACF,IAAI,CAAC,2BAA2B,OAAO,GAAG;EAE1C,SAAS,KAAK;GACZ,QAAQ,MAAM;GACd,MAAM,MAAM;GACZ,aAAa,mBAAmB,OAAmB;GACnD,YAAY,MAAM;EACpB,CAAC;CACH,QAAQ,CAER;AACF;;;;AAKA,SAAgB,gCAAqE;CACnF,OAAO;AACT;;;;;;AAOA,SAAgB,gCAAgC,YAAoB;CAClE,KAAK,IAAI,QAAQ,SAAS,SAAS,GAAG,SAAS,GAAG,SAGhD,IAFgB,SAAS,MAEd,EAAE,eAAe,YAC1B,SAAS,OAAO,OAAO,CAAC;AAG9B;;;;;AAMA,SAAgB,iCAAiC;CAC/C,SAAS,SAAS;AACpB;;;;;;AAOA,SAAgB,iCAAiC,SAA2C;CAC1F,OACE,YAAY,QAAQ,YAAY,KAAK,QAAQ,OAAO,GAAG,QAAQ,KAAK;AAIxE;;;;;;;AAQA,SAAgB,gCAAgC,SAAmC,KAAK;CACtF,MAAM,WAAW,CAAC,GAAG,QAAQ;CAE7B,IAAI,SAAS,WAAW,GAAG,OAAO;CAElC,MAAM,WACJ,SAAS,WAAW,IAChB,4DACA,GAAG,SAAS,OAAO;CAEzB,OAAO,KAAK;EACV,QAAQ;EACR,QAAQ;EACR,SACE,GAAG,SAAS,gKAEZ,SAAS,KAAK,YAAY,OAAO,iCAAiC,OAAO,GAAG,CAAC,CAAC,KAAK,IAAI;EACzF,SAAS,EAAE,UAAU,SAAS;CAChC,CAAC;CAED,OAAO;AACT"}
+{"version":3,"file":"positional-handler-diagnostics.mjs","names":[],"sources":["../../../../../../../../packages/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) {\n    const parameter = bareArrow[1];\n\n    return parameter === undefined ? undefined : [parameter];\n  }\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    const firstParameter = parameters[0];\n\n    return (\n      parameters.length >= 2 && firstParameter !== undefined && !isDestructured(firstParameter)\n    );\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    const suspect = suspects[index];\n\n    if (suspect?.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/resolve-route-rate-limit.mjs

@@ -0,0 +1,47 @@
+import { buildRouteRateLimit } from "./build-route-rate-limit.mjs";
+import baseConfig from "@mongez/config";
+
+//#region ../../packages/core/src/router/resolve-route-rate-limit.ts
+/**
+* Whether static files (the public folder, `router.directory()` mounts and
+* `router.file()` routes) count against the global limiter. Off by default:
+* one page load fetches many assets, which would spend a client's quota on
+* files instead of pages and API calls. `http.rateLimit.staticFiles: true`
+* opts them back in.
+*/
+function staticFilesAreRateLimited() {
+	return baseConfig.get("http.rateLimit.staticFiles") === true;
+}
+/**
+* Resolve a static mount's rate-limit setting: `true` keeps it under the
+* global limiter, `false` exempts it, an object gives it its own limit, and
+* leaving it unset follows `http.rateLimit.staticFiles`.
+*/
+function resolveStaticRateLimit(rateLimit) {
+	if (rateLimit === void 0) return staticFilesAreRateLimited() ? void 0 : false;
+	return resolveExplicitRateLimit(rateLimit);
+}
+/**
+* Resolve a router route's rate-limit setting, identically for production
+* registration and the development wildcard dispatcher.
+*
+* Precedence: the route's own `rateLimit` option, then a
+* `serverOptions.config.rateLimit` passed through to Fastify, then the
+* static-file default for `router.file()` routes, then the global policy.
+*/
+function resolveRouteRateLimit(route) {
+	if (route.rateLimit !== void 0) return resolveExplicitRateLimit(route.rateLimit);
+	const passedThrough = (route.serverOptions?.config)?.rateLimit;
+	if (passedThrough === false) return false;
+	if (typeof passedThrough === "object" && passedThrough !== null) return passedThrough;
+	if (route.$staticFile) return resolveStaticRateLimit(void 0);
+}
+function resolveExplicitRateLimit(rateLimit) {
+	if (rateLimit === true) return void 0;
+	if (rateLimit === false) return false;
+	return buildRouteRateLimit(rateLimit);
+}
+
+//#endregion
+export { resolveRouteRateLimit, resolveStaticRateLimit, staticFilesAreRateLimited };
+//# sourceMappingURL=resolve-route-rate-limit.mjs.map

package/esm/router/resolve-route-rate-limit.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-route-rate-limit.mjs","names":["config"],"sources":["../../../../../../../../packages/core/src/router/resolve-route-rate-limit.ts"],"sourcesContent":["import config from \"@mongez/config\";\nimport { buildRouteRateLimit } from \"./build-route-rate-limit\";\nimport type { Route, RouteRateLimitOptions } from \"./types\";\n\n/**\n * What `@fastify/rate-limit` reads from a route's `config.rateLimit`:\n * `false` exempts the route, an object gives it its own limit and bucket, and\n * `undefined` leaves it under the global policy.\n */\nexport type RouteRateLimitSetting = false | Record<string, unknown> | undefined;\n\n/**\n * Whether static files (the public folder, `router.directory()` mounts and\n * `router.file()` routes) count against the global limiter. Off by default:\n * one page load fetches many assets, which would spend a client's quota on\n * files instead of pages and API calls. `http.rateLimit.staticFiles: true`\n * opts them back in.\n */\nexport function staticFilesAreRateLimited(): boolean {\n  return config.get(\"http.rateLimit.staticFiles\") === true;\n}\n\n/**\n * Resolve a static mount's rate-limit setting: `true` keeps it under the\n * global limiter, `false` exempts it, an object gives it its own limit, and\n * leaving it unset follows `http.rateLimit.staticFiles`.\n */\nexport function resolveStaticRateLimit(\n  rateLimit: RouteRateLimitOptions | boolean | undefined,\n): RouteRateLimitSetting {\n  if (rateLimit === undefined) {\n    return staticFilesAreRateLimited() ? undefined : false;\n  }\n\n  return resolveExplicitRateLimit(rateLimit);\n}\n\n/**\n * Resolve a router route's rate-limit setting, identically for production\n * registration and the development wildcard dispatcher.\n *\n * Precedence: the route's own `rateLimit` option, then a\n * `serverOptions.config.rateLimit` passed through to Fastify, then the\n * static-file default for `router.file()` routes, then the global policy.\n */\nexport function resolveRouteRateLimit(\n  route: Pick<Route, \"rateLimit\" | \"serverOptions\" | \"$staticFile\">,\n): RouteRateLimitSetting {\n  if (route.rateLimit !== undefined) {\n    return resolveExplicitRateLimit(route.rateLimit);\n  }\n\n  const passedThrough: unknown = (\n    route.serverOptions?.config as { rateLimit?: unknown } | undefined\n  )?.rateLimit;\n\n  if (passedThrough === false) return false;\n\n  if (typeof passedThrough === \"object\" && passedThrough !== null) {\n    return passedThrough as Record<string, unknown>;\n  }\n\n  if (route.$staticFile) return resolveStaticRateLimit(undefined);\n\n  return undefined;\n}\n\nfunction resolveExplicitRateLimit(\n  rateLimit: RouteRateLimitOptions | boolean,\n): RouteRateLimitSetting {\n  if (rateLimit === true) return undefined;\n\n  if (rateLimit === false) return false;\n\n  return buildRouteRateLimit(rateLimit);\n}\n"],"mappings":";;;;;;;;;;;AAkBA,SAAgB,4BAAqC;CACnD,OAAOA,WAAO,IAAI,4BAA4B,MAAM;AACtD;;;;;;AAOA,SAAgB,uBACd,WACuB;CACvB,IAAI,cAAc,QAChB,OAAO,0BAA0B,IAAI,SAAY;CAGnD,OAAO,yBAAyB,SAAS;AAC3C;;;;;;;;;AAUA,SAAgB,sBACd,OACuB;CACvB,IAAI,MAAM,cAAc,QACtB,OAAO,yBAAyB,MAAM,SAAS;CAGjD,MAAM,iBACJ,MAAM,eAAe,OAAM,EAC1B;CAEH,IAAI,kBAAkB,OAAO,OAAO;CAEpC,IAAI,OAAO,kBAAkB,YAAY,kBAAkB,MACzD,OAAO;CAGT,IAAI,MAAM,aAAa,OAAO,uBAAuB,MAAS;AAGhE;AAEA,SAAS,yBACP,WACuB;CACvB,IAAI,cAAc,MAAM,OAAO;CAE/B,IAAI,cAAc,OAAO,OAAO;CAEhC,OAAO,oBAAoB,SAAS;AACtC"}

package/esm/router/resolve-route-validation.mjs

@@ -0,0 +1,19 @@
+//#region ../../packages/core/src/router/resolve-route-validation.ts
+/**
+* The validation a route runs: the handler's own `validation`, with the
+* route's `validation` option merged over it (route keys win).
+*/
+function resolveRouteValidation(route) {
+	const own = route.handler?.validation;
+	const routeLevel = route.validation;
+	if (!routeLevel) return own;
+	if (!own) return routeLevel;
+	return {
+		...own,
+		...routeLevel
+	};
+}
+
+//#endregion
+export { resolveRouteValidation };
+//# sourceMappingURL=resolve-route-validation.mjs.map

package/esm/router/resolve-route-validation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-route-validation.mjs","names":[],"sources":["../../../../../../../../packages/core/src/router/resolve-route-validation.ts"],"sourcesContent":["import type { RequestHandlerValidation, Route } from \"./types\";\n\n/**\n * The validation a route runs: the handler's own `validation`, with the\n * route's `validation` option merged over it (route keys win).\n */\nexport function resolveRouteValidation(\n  route: Partial<Pick<Route, \"handler\" | \"validation\">>,\n): RequestHandlerValidation | undefined {\n  const own = route.handler?.validation;\n  const routeLevel = route.validation;\n\n  if (!routeLevel) return own;\n\n  if (!own) return routeLevel;\n\n  return { ...own, ...routeLevel };\n}\n"],"mappings":";;;;;AAMA,SAAgB,uBACd,OACsC;CACtC,MAAM,MAAM,MAAM,SAAS;CAC3B,MAAM,aAAa,MAAM;CAEzB,IAAI,CAAC,YAAY,OAAO;CAExB,IAAI,CAAC,KAAK,OAAO;CAEjB,OAAO;EAAE,GAAG;EAAK,GAAG;CAAW;AACjC"}

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

@@ -1,8 +1,7 @@
 import { RequestHandlerType, RouteOptions } from "./types.mjs";
 import { Router } from "./router.mjs";
-
 //#region ../../packages/core/src/router/route-builder.d.ts
-declare class RouteBuilder {
+export declare class RouteBuilder {
   private readonly router;
   private readonly path;
   private readonly moreOptions;
@@ -120,5 +119,4 @@ declare class RouteBuilder {
   protected withOptions(options?: RouteOptions): RouteOptions;
 }
 //#endregion
-export { RouteBuilder };
 //# sourceMappingURL=route-builder.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"route-builder.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/route-builder.ts"],"mappings":";;;;cAIa,YAAA;EAAA,iBAYQ,MAAA;EAAA,iBACA,IAAA;EAAA,iBACA,WAAA;EAAA,UAbT,WAAA;;;;;;;;;cAWS,MAAA,EAAQ,MAAA,EACR,IAAA,UACA,WAAA,GAAa,YAAA;EA4CqB;;;EApC9C,GAAA,CAAI,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EAyDM;;;;EA3ChD,MAAA,CAAO,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EAwE7B;;;EAhEhB,IAAA,CAAK,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA0F7B;;;;EA5Ed,OAAA,CAAQ,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA4FH;;;EApF3C,GAAA,CAAI,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EAoGI;;;EAvF9C,SAAA,CAAU,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA8H1C;;;EAtHN,KAAA,CAAM,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA0HvC;;;EA7GL,QAAA,CAAS,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA6HN;;;EArHzC,MAAA,CAAO,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA9FjC;;;EA2GZ,SAAA,CAAU,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;;;;;EAahD,IAAA,CAAK,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;;;;;EAQ3C,MAAA,CAAO,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EAhIjC;;;;EAwIZ,IAAA,CAAK,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EAhIV;;;;EAwIjC,MAAA,CAAO,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA1HT;;;;EAkIpC,OAAA,CAAQ,OAAA,EAAS,kBAAA,EAAoB,OAAA,GAAS,YAAA;EA1HZ;;;;;;;;;;EA4IlC,IAAA,CAAK,IAAA,UAAc,OAAA,GAAS,YAAA,GAAoB,YAAA;EAzGhD;;;;;;;;;;;;EA2HA,IAAA,CACL,QAAA;IACE,IAAA,GAAO,kBAAA;IACP,MAAA,GAAS,kBAAA;IACT,IAAA,GAAO,kBAAA;IACP,MAAA,GAAS,kBAAA;IACT,OAAA,GAAU,kBAAA;IACV,KAAA,GAAQ,kBAAA;EAAA,GAEV,OAAA,GAAS,YAAA;EA1FJ;;;EAAA,UAwGG,WAAA,CAAY,OAAA,GAAS,YAAA,GAAiB,YAAA;AAAA"}
+{"version":3,"file":"route-builder.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/route-builder.ts"],"mappings":";;;qBAIa;mBAYQ;mBACA;mBACA;YAbT;IACR;IACA;IACA;IACA;IACA;IACA;IACA;;EAGF,YACmB,QAAQ,QACR,cACA,cAAa;;;;EAQzB,IAAI,SAAS,oBAAoB,UAAS;;;;;EAc1C,OAAO,SAAS,oBAAoB,UAAS;;;;EAQ7C,KAAK,SAAS,oBAAoB,UAAS;;;;;EAc3C,QAAQ,SAAS,oBAAoB,UAAS;;;;EAQ9C,IAAI,SAAS,oBAAoB,UAAS;;;;EAa1C,UAAU,SAAS,oBAAoB,UAAS;;;;EAQhD,MAAM,SAAS,oBAAoB,UAAS;;;;EAa5C,SAAS,SAAS,oBAAoB,UAAS;;;;EAQ/C,OAAO,SAAS,oBAAoB,UAAS;;;;EAa7C,UAAU,SAAS,oBAAoB,UAAS;;;;;EAahD,KAAK,SAAS,oBAAoB,UAAS;;;;;EAQ3C,OAAO,SAAS,oBAAoB,UAAS;;;;;EAQ7C,KAAK,SAAS,oBAAoB,UAAS;;;;;EAQ3C,OAAO,SAAS,oBAAoB,UAAS;;;;;EAQ7C,QAAQ,SAAS,oBAAoB,UAAS;;;;;;;;;;;EAkB9C,KAAK,cAAc,UAAS,eAAoB;;;;;;;;;;;;;EAkBhD,KACL;IACE,OAAO;IACP,SAAS;IACT,OAAO;IACP,SAAS;IACT,UAAU;IACV,QAAQ;KAEV,UAAS;;;;YAcD,YAAY,UAAS,eAAiB"}

package/esm/router/route-guard-names.mjs

@@ -0,0 +1,30 @@
+//#region ../../packages/core/src/router/route-guard-names.ts
+/**
+* The names both route-guard checks share: the dev-server warning (which
+* reads registered routes) and `warlock check`'s `WL9006` (which reads the
+* source of `routes.ts` files). Keeping one definition means the two never
+* disagree about what counts as a mutating route or an auth guard.
+*
+* Side-effect free: imports nothing.
+*/
+/** HTTP methods that change state; a route answering one needs a guard or `public: true`. */
+const MUTATING_HTTP_METHODS = /* @__PURE__ */ new Set([
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+/** Middleware named like this counts as a guard when it carries no marker. */
+const GUARD_NAME_PATTERN = /auth|guard/i;
+/** Whether an HTTP method (any case) mutates state: POST, PUT, PATCH or DELETE. */
+function isMutatingHttpMethod(method) {
+	return MUTATING_HTTP_METHODS.has(method.toUpperCase());
+}
+/** Whether a middleware name reads as an auth guard: it contains `auth` or `guard`. */
+function isAuthGuardName(name) {
+	return GUARD_NAME_PATTERN.test(name);
+}
+
+//#endregion
+export { isAuthGuardName, isMutatingHttpMethod };
+//# sourceMappingURL=route-guard-names.mjs.map

package/esm/router/route-guard-names.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-guard-names.mjs","names":[],"sources":["../../../../../../../../packages/core/src/router/route-guard-names.ts"],"sourcesContent":["/**\n * The names both route-guard checks share: the dev-server warning (which\n * reads registered routes) and `warlock check`'s `WL9006` (which reads the\n * source of `routes.ts` files). Keeping one definition means the two never\n * disagree about what counts as a mutating route or an auth guard.\n *\n * Side-effect free: imports nothing.\n */\n\n/** HTTP methods that change state; a route answering one needs a guard or `public: true`. */\nconst MUTATING_HTTP_METHODS: ReadonlySet<string> = new Set([\"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\n/** Middleware named like this counts as a guard when it carries no marker. */\nconst GUARD_NAME_PATTERN = /auth|guard/i;\n\n/** Whether an HTTP method (any case) mutates state: POST, PUT, PATCH or DELETE. */\nexport function isMutatingHttpMethod(method: string): boolean {\n  return MUTATING_HTTP_METHODS.has(method.toUpperCase());\n}\n\n/** Whether a middleware name reads as an auth guard: it contains `auth` or `guard`. */\nexport function isAuthGuardName(name: string): boolean {\n  return GUARD_NAME_PATTERN.test(name);\n}\n"],"mappings":";;;;;;;;;;AAUA,MAAM,wCAA6C,IAAI,IAAI;CAAC;CAAQ;CAAO;CAAS;AAAQ,CAAC;;AAG7F,MAAM,qBAAqB;;AAG3B,SAAgB,qBAAqB,QAAyB;CAC5D,OAAO,sBAAsB,IAAI,OAAO,YAAY,CAAC;AACvD;;AAGA,SAAgB,gBAAgB,MAAuB;CACrD,OAAO,mBAAmB,KAAK,IAAI;AACrC"}

package/esm/router/route-name-method-suffix.d.mts

@@ -17,7 +17,7 @@
  * The suffix `Router.add` appends to a route name already claimed by another
  * method.
  */
-declare function routeNameMethodSuffix(method: string): string;
+export declare function routeNameMethodSuffix(method: string): string;
 /**
  * Whether `registeredName` is what the router would have registered for a
  * route whose name was DERIVED as `derivedName`.
@@ -27,7 +27,6 @@ declare function routeNameMethodSuffix(method: string): string;
  * match — a `.get` suffix is accepted only where the router itself could have
  * added one, and any other difference is still a difference.
  */
-declare function matchesDerivedRouteName(derivedName: string, registeredName: string, method: string): boolean;
+export declare function matchesDerivedRouteName(derivedName: string, registeredName: string, method: string): boolean;
 //#endregion
-export { matchesDerivedRouteName, routeNameMethodSuffix };
 //# sourceMappingURL=route-name-method-suffix.d.mts.map

package/esm/router/route-name-method-suffix.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"route-name-method-suffix.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/route-name-method-suffix.ts"],"mappings":";;AAmBA;;;;AAAoD;AAapD;;;;;;;;AAGgB;;;;AAAA,iBAhBA,qBAAA,CAAsB,MAAc;;;;;;;;;;iBAapC,uBAAA,CACd,WAAA,UACA,cAAA,UACA,MAAA"}
+{"version":3,"file":"route-name-method-suffix.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/route-name-method-suffix.ts"],"mappings":";;;;;;;;;;;;;;;;;;;wBAmBgB,sBAAsB;;;;;;;;;;wBAatB,wBACd,qBACA,wBACA"}

package/esm/router/route-name-taken-error.d.mts

@@ -0,0 +1,12 @@
+import { WarlockError } from "../errors/warlock-error.mjs";
+//#region ../../packages/core/src/router/route-name-taken-error.d.ts
+/**
+ * Thrown when a route is registered under a name another route with the same
+ * method already claimed. Pages and API routes share one name namespace.
+ */
+export declare class RouteNameTakenError extends WarlockError {
+  readonly routeName: string;
+  constructor(routeName: string, message: string);
+}
+//#endregion
+//# sourceMappingURL=route-name-taken-error.d.mts.map

package/esm/router/route-name-taken-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-name-taken-error.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/route-name-taken-error.ts"],"mappings":";;;;;;qBAMa,4BAA4B;WAErB;EADlB,YACkB,mBAChB"}

package/esm/router/route-name-taken-error.mjs

@@ -0,0 +1,18 @@
+import { WarlockError } from "../errors/warlock-error.mjs";
+
+//#region ../../packages/core/src/router/route-name-taken-error.ts
+/**
+* Thrown when a route is registered under a name another route with the same
+* method already claimed. Pages and API routes share one name namespace.
+*/
+var RouteNameTakenError = class extends WarlockError {
+	constructor(routeName, message) {
+		super("WL3001", message);
+		this.routeName = routeName;
+		this.name = "RouteNameTakenError";
+	}
+};
+
+//#endregion
+export { RouteNameTakenError };
+//# sourceMappingURL=route-name-taken-error.mjs.map

package/esm/router/route-name-taken-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-name-taken-error.mjs","names":[],"sources":["../../../../../../../../packages/core/src/router/route-name-taken-error.ts"],"sourcesContent":["import { WarlockError } from \"../errors/warlock-error\";\n\n/**\n * Thrown when a route is registered under a name another route with the same\n * method already claimed. Pages and API routes share one name namespace.\n */\nexport class RouteNameTakenError extends WarlockError {\n  public constructor(\n    public readonly routeName: string,\n    message: string,\n  ) {\n    super(\"WL3001\", message);\n    this.name = \"RouteNameTakenError\";\n  }\n}\n"],"mappings":";;;;;;;AAMA,IAAa,sBAAb,cAAyC,aAAa;CACpD,AAAO,YACL,AAAgB,WAChB,SACA;EACA,MAAM,UAAU,OAAO;EAHP;EAIhB,KAAK,OAAO;CACd;AACF"}

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

@@ -1,11 +1,10 @@
 import { Route } from "./types.mjs";
-
 //#region ../../packages/core/src/router/route-registry.d.ts
 /**
  * Route Registry
  * Manages dynamic route matching using find-my-way for HMR support
  */
-declare class RouteRegistry {
+export declare class RouteRegistry {
   private router;
   constructor();
   /**
@@ -30,5 +29,4 @@ declare class RouteRegistry {
   getRouteCount(): number;
 }
 //#endregion
-export { RouteRegistry };
 //# sourceMappingURL=route-registry.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"route-registry.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/route-registry.ts"],"mappings":";;;;;AAuBA;;cAAa,aAAA;EAAA,QACH,MAAA;;EAgDI;;;EAjCL,QAAA,CAAS,MAAA,EAAQ,KAAA;EAfhB;;;EAkCD,aAAA,CAAc,KAAA,EAAO,KAAA;EAnBZ;;;;EA8BT,IAAA,CACL,MAAA,UACA,GAAA;IACG,KAAA,EAAO,KAAA;IAAO,MAAA,EAAQ,MAAA;EAAA;EAAf;;;EAqBL,aAAA;AAAA"}
+{"version":3,"file":"route-registry.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/router/route-registry.ts"],"mappings":";;;;;;qBAuBa;UACH;EAER;;;;EAaO,SAAS,QAAQ;;;;EAmBjB,cAAc,OAAO;;;;;EAWrB,KACL,gBACA;IACG,OAAO;IAAO,QAAQ;;;;;EAqBpB"}

package/esm/router/router.d.mts

@@ -1,11 +1,10 @@
 import { FastifyInstance } from "../http/server.mjs";
-import { GroupedRoutesOptions, NamedApiRoute, NamedApiRoutesOptions, RequestHandler, RequestHandlerType, ResourceMethod, Route, RouteOptions, RouteResource, RouterGroupCallback, RouterStacks } from "./types.mjs";
+import { GroupedRoutesOptions, NamedApiRoute, NamedApiRoutesOptions, RequestHandler, RequestHandlerType, ResourceMethod, Route, RouteOptions, RouteResource, RouterGroupCallback, RouterStacks, StaticMountOptions } from "./types.mjs";
 import { RouteBuilder } from "./route-builder.mjs";
 import { FastifyHttpProxyOptions } from "@fastify/http-proxy";
 import { FastifyStaticOptions } from "@fastify/static";
-
 //#region ../../packages/core/src/router/router.d.ts
-declare class Router {
+export declare class Router {
   /**
    * Routes list
    */
@@ -24,6 +23,11 @@ declare class Router {
    * {@link routes}; mutations and collision checks use this isolated draft.
    */
   private routeReplacementTransaction?;
+  /**
+   * Set by the dev server: whether to warn about mutating routes that have no
+   * auth middleware and no `public: true` (`http.warnUnguardedRoutes`).
+   */
+  private warnUnguardedRoutes;
   /**
    * Router Instance
    */
@@ -31,7 +35,10 @@ declare class Router {
   /**
    * Static paths
    */
-  protected staticDirectories: FastifyStaticOptions[];
+  protected staticDirectories: {
+    options: FastifyStaticOptions;
+    rateLimit: StaticMountOptions["rateLimit"];
+  }[];
   /**
    * Event listeners
    */
@@ -59,32 +66,43 @@ declare class Router {
    */
   redirect(from: string, to: string, redirectMode?: "temporary" | "permanent"): this;
   /**
-   * Server static folder
+   * Serve a static folder.
+   *
+   * Static mounts are exempt from the global rate limiter by default; set
+   * `http.rateLimit.staticFiles: true` to count every mount, or pass
+   * `{ rateLimit }` to decide for this mount alone: `true` counts it against
+   * the global limiter, `false` exempts it, and an object gives it its own
+   * limit and bucket.
+   *
+   * @example
+   * router.directory({ root: rootPath("docs"), prefix: "/docs/" });
+   * router.directory({ root: rootPath("exports"), prefix: "/exports/" }, { rateLimit: true });
    */
-  directory(options: FastifyStaticOptions): this;
+  directory(options: FastifyStaticOptions, mountOptions?: StaticMountOptions): this;
+  /** Declare static routes at boot; load the upstream sender on the first file request. */
+  protected registerStaticDirectories(server: FastifyInstance): void;
   /**
-   * Register every `directory()` with `@fastify/static`. The plugin is
-   * imported only when at least one directory was declared: loading it is not
-   * free (its directory-listing module calls `os.cpus()` at load), and an app
-   * that serves no static folder should not pay for it (WR-027).
+   * Register a GET route that serves a static file. Like `directory()`, it is
+   * exempt from the global rate limiter unless `http.rateLimit.staticFiles`
+   * or its own `rateLimit` says otherwise.
    */
-  protected registerStaticDirectories(server: FastifyInstance): void;
+  protected addStaticFileRoute(path: string, handler: RequestHandler, mountOptions?: StaticMountOptions): this;
   /**
    * Serve file
    */
-  file(path: string, location: string, cacheTime?: number): this;
+  file(path: string, location: string, cacheTime?: number, mountOptions?: StaticMountOptions): this;
   /**
    * Serve cached file, it will cache the file to 1 year by default
    */
-  cachedFile(path: string, location: string, cacheTime?: number): this;
+  cachedFile(path: string, location: string, cacheTime?: number, mountOptions?: StaticMountOptions): this;
   /**
    * Serve list of files
    */
-  files(files: Record<string, string>, cacheTime?: number): void;
+  files(files: Record<string, string>, cacheTime?: number, mountOptions?: StaticMountOptions): void;
   /**
    * Serve list of cached files, it will cache the file to 1 year by default
    */
-  cachedFiles(files: Record<string, string>, cacheTime?: number): void;
+  cachedFiles(files: Record<string, string>, cacheTime?: number, mountOptions?: StaticMountOptions): void;
   /**
    * Add proxy route
    */
@@ -232,7 +250,6 @@ declare class Router {
    */
   private handleRoute;
 }
-declare const router: Router;
+export declare const router: Router;
 //#endregion
-export { Router, router };
 //# sourceMappingURL=router.d.mts.map