@znight/http 0.1.3 → 0.2.0

package/README.md

@@ -1222,8 +1222,18 @@ export class AdminController {
 HttpPlugin.configure({ guards: [AuthGuard] })
 ```
 
-`decorator.get(ctx)` reads the route metadata (`ctx.route.meta`) with its type. Guards,
-interceptors and mappers are providers: they may be request-scoped (resolved per request) and have
+`decorator.get(ctx)` reads the route metadata (`ctx.route.meta`) with its type. It accepts any
+`RouteMetaCarrier` (`{ route?: { meta } }`), not only an `HttpContext`: the contexts of other
+transports that reuse route decorators (a GraphQL resolver, a WebSocket gateway) expose their
+effective metadata the same way, so one guard helper serves every transport:
+
+```ts
+import type { RouteMetaCarrier } from '@znight/http'
+
+const isPublic = (ctx: RouteMetaCarrier): boolean => Public.get(ctx) === true
+```
+
+Guards, interceptors and mappers are providers: they may be request-scoped (resolved per request) and have
 dependencies. Plugin options also accept instances (`guards: [new IpAllowList(['10.0.0.0/8'])]`).
 
 ## Route decisions
@@ -1493,13 +1503,18 @@ app.hooks.wrap('http:request', async (event, next) => {
 stream, `run` resolves when the stream opens (`status: 200`): durations measure the time to open.
 A stream-lifetime hook is not provided.
 
-When no `http:request` wrapper or listener is registered (and CORS is off), routes (other than
-`@All`) without guards, interceptors, `@Sse`, `@Res()` or `@Header` take a fast lane: the plugin
-decides at boot what the pipeline would do for them, runs a synchronous handler without creating a
-promise and builds the headers of a JSON reply from a template. The replies are the same as through
-the full pipeline (a thrown error, an `HttpResponse` or anything unusual continues there, in the
-same request scope; a promise is awaited first); registering a hook simply sends every request
-through the full pipeline again.
+When CORS is off, routes (other than `@All`) without guards, interceptors, `@Sse`, `@Res()` or
+`@Header` take a fast lane: the plugin decides at boot what the pipeline would do for them, runs a
+synchronous handler without creating a promise and builds the headers of a JSON reply from a
+template. A plain object or array result is served there, and so is an `HttpResponse` whose body is
+one, with no cookie and no header other than a lower-case `content-type` (`HttpResponse.ok(body)`,
+an explicit status, a custom JSON media type), except on `@Head` routes. The replies are the same as
+through the full pipeline (a thrown error, another `HttpResponse` or anything unusual continues
+there, in the same request scope; a promise is awaited first). The
+lane runs the `http:request` hooks too: listeners keep it synchronous, and wrappers (such as those of
+`@znight/observability`) see the same event, in the same request scope and async context, as with
+the full pipeline; a reply whose wrappers added response headers or cookies is completed like any
+other.
 
 ## Plugin options
 
@@ -1587,6 +1602,7 @@ export class StatusPlugin implements Plugin, PluginHttpRoutes {
         handler: ctx => ({ up: true }), // (ctx: HttpContext) => result, serialised like a controller result
         meta: [Public.meta()], // route metadata: read by guards, checked by the route decision check
         guards: [], // extra guards (classes or instances)
+        bodyLimit: '100kb', // optional: this route's body limit, instead of the HttpPlugin bodyLimit
       },
     ]
   }
@@ -1599,9 +1615,12 @@ export class StatusPlugin implements Plugin, PluginHttpRoutes {
   then the route `guards`, the handler and the exception mappers. Global interceptors do not wrap
   plugin routes (a response envelope would break a document). The body is read lazily
   (`ctx.parseBody()`). `GET` routes answer `HEAD`; `ALL` works as for controllers.
+- `bodyLimit` (a `ByteSize`: `1048576`, `'100kb'`, `Infinity`, the grammar of the plugin option)
+  replaces the `HttpPlugin` `bodyLimit` for that route only, lower or higher, like `@BodyLimit` on a
+  controller route: reading a larger body answers 413. Without it, the plugin limit applies.
 - `meta` entries (`decorator.meta(value)`, one per group) are the route metadata. A required group
   needs a decision there too: without one the boot fails (ZNIGHT023), with a hint naming the plugin.
-- An invalid route (method, path grammar, name, handler, meta) or a collision with another route is
+- An invalid route (method, path grammar, name, handler, meta, body limit) or a collision with another route is
   ZNIGHT007 naming the plugin. `HttpPlugin.routes` lists the routes with `source: '<plugin name>'`.
 
 ## Adapters
@@ -2293,6 +2312,62 @@ Controllers are stored in identity order of the classes; sort them by `token` fo
 output. The effective metadata of a route is the controller's entries whose `group` has no entry on
 the route, then the route's entries.
 
+### Route metadata in other extensions
+
+Extensions whose own targets carry route decorators (WebSocket gateways, GraphQL resolvers) read
+them with the functions of `@znight/http/compiler`, which apply exactly the rules of controllers and
+routes (RFC 0001 groups). They are stable API, like the types above, and the entry stays
+runtime-free (it never loads the HTTP runtime):
+
+| Function                             | What it does                                                                                                                                                                                                                                                                                              |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `readRouteMeta(ctx, cls, method?)`   | The `MetaEntry[]` of the route decorators applied to a class (`method` omitted) or to one of its methods, in source order. Works with the `AnalyzeContext` of any extension. Problems (uncalled decorator, two decisions of one group...) are reported as ZNIGHT005, once per call: read each target once |
+| `effectiveRouteMeta(classMeta, own)` | The effective metadata of a method: the class entries whose group the method does not decide, then the method entries (the rule of `ctx.route.meta`)                                                                                                                                                      |
+| `requiredRouteGroups(ctx, applied?)` | The `RequiredRouteGroup[]` of the application (in the `ValidateContext` of any extension): every group declared `required`, applied anywhere or not. `applied` are the entries the caller read. Inconsistent definitions are left out (the http extension reports them)                                   |
+
+A `RequiredRouteGroup` has `group`, `decorators` (`RouteGroupMember[]`, source order: `identity`,
+`name`, `key`, `group`, `required`, `definition`, `flag`) and `suggestion`
+(`@Public(), @Authenticated() or @Roles(...)`). A target of the extension without a decision of a
+required group is **ZNIGHT023**, reported by the extension itself:
+
+```ts
+import type { CompilerExtension, Location } from '@znight/compiler'
+import type { MetaEntry } from '@znight/http/compiler'
+
+import { readRouteMeta, requiredRouteGroups } from '@znight/http/compiler'
+
+interface GatewayData {
+  readonly name: string
+  readonly meta: readonly MetaEntry[] // the class entries (methods: effectiveRouteMeta(classMeta, own))
+  readonly location: Location
+}
+
+const ws: CompilerExtension<GatewayData> = {
+  apiVersion: 1,
+  name: 'ws',
+  decorators: { '@acme/ws#Gateway': { targets: ['class'], params: [] } },
+  analyzeClass(cls, ctx) {
+    ctx.store({ name: cls.displayName, meta: readRouteMeta(ctx, cls), location: cls.location })
+  },
+  validate(ctx) {
+    const required = requiredRouteGroups(
+      ctx,
+      ctx.stored.flatMap(gateway => gateway.meta),
+    )
+    for (const gateway of ctx.stored)
+      for (const group of required)
+        if (!gateway.meta.some(entry => entry.group === group.group))
+          ctx.report({
+            code: 'ZNIGHT023',
+            severity: 'error',
+            message: `${gateway.name} has no "${group.group}" decision`,
+            location: gateway.location,
+            hints: [`Add ${group.suggestion} to ${gateway.name}`],
+          })
+  },
+}
+```
+
 ## Writing an adapter
 
 An adapter implements `HttpAdapter` (exported types): it routes requests to the handlers given by

package/dist/compiler.d.mts

@@ -1,5 +1,5 @@
 import { _ as HttpMethod, y as HttpParamSource } from "./adapter-J0UXFnNM.mjs";
-import { ClassRef, CompilerExtension, Location, StaticValue, ValueRef } from "@znight/compiler";
+import { AnalyzeContext, ClassInfo, ClassRef, CompilerExtension, Location, MethodInfo, StaticValue, ValidateContext, ValueRef } from "@znight/compiler";
 /** Primitive coercions (`coerce.<kind>`). */
 type ScalarCoercion = "string" | "number" | "integer" | "boolean" | "bigint" | "date";
 /**
@@ -150,7 +150,82 @@ interface HttpControllerData {
   /** Location of the base path argument (the decorator when absent). */
   readonly pathLocation: Location;
 }
+/** A route decorator definition of the application (`export const Roles = createRouteDecorator(...)`). */
+interface RouteGroupMember {
+  /** Canonical identity of the decorator `const` (`src/auth/access.ts#Roles`). */
+  readonly identity: string;
+  /** Name of the `const` (`Roles`). */
+  readonly name: string;
+  readonly key: string;
+  /** Decision group (`options.group ?? key`). */
+  readonly group: string;
+  readonly required: boolean;
+  /** Location of the definition. */
+  readonly definition: Location;
+  /**
+   * A flag (`@Public()`): created without type argument, and applied without argument wherever it
+   * was seen. Decides how the decorator is suggested: `@Public()` or `@Roles(...)`.
+   */
+  readonly flag: boolean;
+}
+/** A required route decorator group: every route-like target must carry a decision of it. */
+interface RequiredRouteGroup {
+  /** Group name (`access`). */
+  readonly group: string;
+  /** The decorators of the group, in source order (file, then position). Never empty. */
+  readonly decorators: readonly RouteGroupMember[];
+  /** The decorators as a hint: `@Public(), @Authenticated() or @Roles(...)`. */
+  readonly suggestion: string;
+}
+/**
+ * The required route decorator groups of the application (RFC 0001): what every route-like target
+ * of another extension (a gateway, a GraphQL root field) must decide, exactly as HTTP routes must.
+ * A target without a decision of a returned group is **ZNIGHT023**, reported by the caller.
+ *
+ * `applied` are the route metadata entries the caller read on its own targets
+ * ({@link readRouteMeta}): they make decorators known even when the compiler has no
+ * `definitionsOf`, and refine how flags are suggested. Inconsistent definitions are left out and
+ * not reported here: the http extension reports them (ZNIGHT005) once.
+ *
+ * ```ts
+ * validate(ctx) {
+ *   const required = requiredRouteGroups(ctx, ctx.stored.flatMap(gateway => gateway.meta))
+ *   for (const gateway of ctx.stored)
+ *     for (const group of required)
+ *       if (!gateway.meta.some(entry => entry.group === group.group))
+ *         ctx.report({ code: 'ZNIGHT023', severity: 'error', message: `${gateway.name} has no "${group.group}" decision`,
+ *           location: gateway.location, hints: [`Add ${group.suggestion} to ${gateway.name}`] })
+ * }
+ * ```
+ */
+export declare function requiredRouteGroups(ctx: ValidateContext<unknown>, applied?: Iterable<MetaEntry>): readonly RequiredRouteGroup[];
+/**
+ * The route metadata entries of a class (`method` omitted) or of one of its methods: the route
+ * decorators (`createRouteDecorator` consts) applied to that target, in source order, read exactly
+ * as the http extension reads controllers and routes (keys, statically evaluated values, groups,
+ * `required`). Problems are reported as ZNIGHT005 through `ctx`, once per call: read each target
+ * once. Decorators that are not route decorators are ignored.
+ *
+ * Works with the analysis context of any extension. The entries of a target are its own: combine a
+ * class and a method with {@link effectiveRouteMeta}.
+ *
+ * ```ts
+ * analyzeClass(cls, ctx) {
+ *   const classMeta = readRouteMeta(ctx, cls)
+ *   for (const method of cls.methods) {
+ *     const meta = effectiveRouteMeta(classMeta, readRouteMeta(ctx, cls, method))
+ *   }
+ * }
+ * ```
+ */
+export declare function readRouteMeta(ctx: AnalyzeContext<unknown>, cls: ClassInfo, method?: MethodInfo): MetaEntry[];
+/**
+ * The effective metadata of a method from the entries of its class and its own (RFC 0001 §5.1):
+ * the class entries, except those of a group the method decides itself, then the method entries.
+ * The same rule as `ctx.route.meta` at runtime.
+ */
+export declare function effectiveRouteMeta(classMeta: readonly MetaEntry[], methodMeta: readonly MetaEntry[]): MetaEntry[];
 /** The `@znight/http` compiler extension. */
 declare const http: CompilerExtension<HttpControllerData>;
-export { type CoercionPlan, type HttpControllerData, type HttpParamData, type HttpRouteData, type MetaEntry, type ParamCoercion, type ScalarCoercion, type SseRouteData, type UploadData, http as default };
+export { type CoercionPlan, type HttpControllerData, type HttpParamData, type HttpRouteData, type MetaEntry, type ParamCoercion, type RequiredRouteGroup, type RouteGroupMember, type ScalarCoercion, type SseRouteData, type UploadData, http as default };
 //# sourceMappingURL=compiler.d.mts.map

package/dist/compiler.mjs

@@ -514,6 +514,38 @@ function routeMeta(ctx, cls, decorators, target) {
 	}
 	return entries;
 }
+/**
+* The route metadata entries of a class (`method` omitted) or of one of its methods: the route
+* decorators (`createRouteDecorator` consts) applied to that target, in source order, read exactly
+* as the http extension reads controllers and routes (keys, statically evaluated values, groups,
+* `required`). Problems are reported as ZNIGHT005 through `ctx`, once per call: read each target
+* once. Decorators that are not route decorators are ignored.
+*
+* Works with the analysis context of any extension. The entries of a target are its own: combine a
+* class and a method with {@link effectiveRouteMeta}.
+*
+* ```ts
+* analyzeClass(cls, ctx) {
+*   const classMeta = readRouteMeta(ctx, cls)
+*   for (const method of cls.methods) {
+*     const meta = effectiveRouteMeta(classMeta, readRouteMeta(ctx, cls, method))
+*   }
+* }
+* ```
+*/
+function readRouteMeta(ctx, cls, method) {
+	return method === void 0 ? routeMeta(ctx, cls, cls.decorators, cls.displayName) : routeMeta(ctx, cls, method.decorators, `${cls.displayName}.${method.name}`);
+}
+/**
+* The effective metadata of a method from the entries of its class and its own (RFC 0001 §5.1):
+* the class entries, except those of a group the method decides itself, then the method entries.
+* The same rule as `ctx.route.meta` at runtime.
+*/
+function effectiveRouteMeta(classMeta, methodMeta) {
+	if (methodMeta.length === 0) return [...classMeta];
+	const decided = new Set(methodMeta.map((entry) => entry.group));
+	return [...classMeta.filter((entry) => !decided.has(entry.group)), ...methodMeta];
+}
 /** `true` when the decorator is a route metadata decorator. */
 function isRouteMetaDecorator(ctx, decorator) {
 	return decorator.owner === void 0 && decorator.identity !== void 0 && resolveRouteDecorator(ctx, decorator.identity).kind !== "other";
@@ -661,7 +693,7 @@ function analyzeHttpClass(cls, ctx) {
 	const basePath = normalizePath(options.path);
 	const guards = classRefs(ctx, cls, cls.decorators, Ids.UseGuard, "guard");
 	const interceptors = classRefs(ctx, cls, cls.decorators, Ids.UseInterceptor, "interceptor");
-	const meta = routeMeta(ctx, cls, cls.decorators, cls.displayName);
+	const meta = readRouteMeta(ctx, cls);
 	const bodyLimit = bodyLimitOf(ctx, cls.decorators);
 	const routes = [];
 	for (const method of cls.methods) routes.push(...analyzeMethod(ctx, cls, method, basePath, bodyLimit));
@@ -796,7 +828,7 @@ function analyzeMethod(ctx, cls, method, basePath, controllerBodyLimit) {
 	let headers = responseHeaders(ctx, decorators);
 	const guards = classRefs(ctx, cls, decorators, Ids.UseGuard, "guard");
 	const interceptors = classRefs(ctx, cls, decorators, Ids.UseInterceptor, "interceptor");
-	const meta = routeMeta(ctx, cls, decorators, where);
+	const meta = readRouteMeta(ctx, cls, method);
 	const bodySchema = bodyValidation !== void 0 && !params.some((param) => param.source === "body") ? bodyValidation.schema : void 0;
 	let rawResponse = params.some((param) => param.source === "response");
 	const bodyLimit = bodyLimitOf(ctx, decorators) ?? controllerBodyLimit;
@@ -1954,77 +1986,26 @@ function itemCoercer(ctx, helpers, plan) {
 		default: return ctx.member(helpers.coerce(), plan.kind);
 	}
 }
-// src/compiler/validate.ts
-/** Validates the routes of every controller. */
-function validateHttp(ctx) {
-	const controllers = [...ctx.stored].sort((a, b) => compareStrings(a.token, b.token));
-	const registered = /* @__PURE__ */ new Map();
-	for (const controller of controllers) {
-		const baseIssue = checkRoutePath(controller.rawBasePath);
-		if (baseIssue !== void 0) {
-			invalidRoute(ctx, controller.pathLocation, `Invalid base path ${JSON.stringify(controller.rawBasePath)} of ${controller.displayName}: ${baseIssue.message}`, GRAMMAR_HINTS);
-			continue;
-		}
-		for (const route of controller.routes) {
-			const where = `${controller.displayName}.${route.handler}`;
-			const ownIssue = checkRoutePath(route.rawPath);
-			const issue = ownIssue ?? checkRoutePath(route.fullPath);
-			if (issue !== void 0) {
-				const path = ownIssue === void 0 ? route.fullPath : route.rawPath;
-				invalidRoute(ctx, route.pathLocation, `Invalid route path ${JSON.stringify(path)} of ${where}: ${issue.message}`, GRAMMAR_HINTS);
-				continue;
-			}
-			const parsed = parseRoutePath(route.fullPath);
-			checkParams(ctx, route, parsed, where);
-			const key = `${route.method} ${parsed.shape}`;
-			const previous = registered.get(key);
-			if (previous === void 0) {
-				registered.set(key, {
-					where,
-					route
-				});
-				continue;
-			}
-			ctx.report({
-				code: Codes.InvalidRoute,
-				severity: "error",
-				message: `Duplicate route ${route.method} ${route.fullPath}: ${where} conflicts with ${previous.where} (${previous.route.method} ${previous.route.fullPath})`,
-				location: route.location,
-				hints: ["Two routes with the same method and the same path shape (parameter names aside) cannot coexist"],
-				related: [{
-					message: `${previous.where} is declared here`,
-					location: previous.route.location
-				}]
-			});
-		}
-	}
-	validateDecisions(ctx, controllers);
-}
+// src/compiler/route-groups.ts
 /**
-* Every route decorator definition, sorted by identity: the applied ones (first usage) and, when
-* the compiler provides `definitionsOf`, the ones applied nowhere (invalid ones are left to the
-* usages, which report them).
+* Every route decorator definition, sorted by identity: the applied ones (`applied`, first usage
+* wins) and, when the compiler provides `definitionsOf`, the ones applied nowhere (invalid ones are
+* left to the usages, which report them).
 */
-function routeDecoratorDefinitions(ctx, controllers) {
+function routeDecoratorDefinitions(ctx, applied) {
 	const definitions = /* @__PURE__ */ new Map();
-	const visit = (entries) => {
-		for (const entry of entries) {
-			const known = definitions.get(entry.identity);
-			if (known === void 0) definitions.set(entry.identity, {
-				identity: entry.identity,
-				name: entry.decorator,
-				key: entry.key,
-				group: entry.group,
-				required: entry.required,
-				definition: entry.definition,
-				flag: entry.value === true
-			});
-			else if (entry.value !== true) known.flag = false;
-		}
-	};
-	for (const controller of controllers) {
-		visit(controller.meta);
-		for (const route of controller.routes) visit(route.meta);
+	for (const entry of applied) {
+		const known = definitions.get(entry.identity);
+		if (known === void 0) definitions.set(entry.identity, {
+			identity: entry.identity,
+			name: entry.decorator,
+			key: entry.key,
+			group: entry.group,
+			required: entry.required,
+			definition: entry.definition,
+			flag: entry.value === true
+		});
+		else if (entry.value !== true) known.flag = false;
 	}
 	const all = typeof ctx.definitionsOf === "function" ? ctx.definitionsOf(Ids.createRouteDecorator) : [];
 	for (const found of all) {
@@ -2051,20 +2032,26 @@ function routeDecoratorDefinitions(ctx, controllers) {
 	return [...definitions.values()].sort((a, b) => compareStrings(a.identity, b.identity));
 }
 /**
-* Route decorator groups (RFC 0001 §5.1): every definition of a key uses the same options and the
-* decorators of a group agree on `required` (ZNIGHT005, at the second definition); every route has
-* a decision of every required group, its own or its controller's (ZNIGHT023).
+* The route decorator groups of the application (RFC 0001 §5.1): every definition of a key must use
+* the same options and the decorators of a group must agree on `required` (a conflict is returned
+* at the second definition, which is then ignored); the required groups with their decorators.
+* `applied` are the entries of the targets the caller analysed (their first usage of a decorator
+* wins over its `definitionsOf` entry).
 */
-function validateDecisions(ctx, controllers) {
-	const definitions = routeDecoratorDefinitions(ctx, controllers);
-	if (definitions.length === 0) return;
+function analyzeRouteGroups(ctx, applied) {
+	const definitions = routeDecoratorDefinitions(ctx, applied);
+	if (definitions.length === 0) return {
+		conflicts: [],
+		required: []
+	};
+	const conflicts = [];
 	const byKey = /* @__PURE__ */ new Map();
 	const byGroup = /* @__PURE__ */ new Map();
 	const members = /* @__PURE__ */ new Map();
 	for (const definition of definitions) {
 		const sameKey = byKey.get(definition.key);
 		if (sameKey !== void 0 && (sameKey.group !== definition.group || sameKey.required !== definition.required)) {
-			ctx.report({
+			conflicts.push({
 				code: Codes.InvalidDecorator,
 				severity: "error",
 				message: `The route decorator ${definition.name} defines the key "${definition.key}" with ${describeOptions(definition)}, but ${sameKey.name} defines it with ${describeOptions(sameKey)}`,
@@ -2079,7 +2066,7 @@ function validateDecisions(ctx, controllers) {
 		}
 		const sameGroup = byGroup.get(definition.group);
 		if (sameGroup !== void 0 && sameGroup.required !== definition.required) {
-			ctx.report({
+			conflicts.push({
 				code: Codes.InvalidDecorator,
 				severity: "error",
 				message: `The "${definition.group}" group is ${definition.required ? "" : "not "}required for ${definition.name} but ${sameGroup.required ? "" : "not "}required for ${sameGroup.name}`,
@@ -2098,7 +2085,112 @@ function validateDecisions(ctx, controllers) {
 		list.push(definition);
 		members.set(definition.group, list);
 	}
-	const required = [...byGroup.values()].filter((definition) => definition.required);
+	const required = [];
+	for (const first of byGroup.values()) {
+		if (!first.required) continue;
+		const decorators = [...members.get(first.group) ?? [first]].sort((a, b) => compareStrings(a.definition.file, b.definition.file) || a.definition.start - b.definition.start).map((member) => Object.freeze({ ...member }));
+		const usages = decorators.map((member) => `@${member.name}(${member.flag ? "" : "..."})`);
+		const suggestion = usages.length === 1 ? usages[0] : `${usages.slice(0, -1).join(", ")} or ${usages.at(-1)}`;
+		required.push(Object.freeze({
+			group: first.group,
+			decorators: Object.freeze(decorators),
+			suggestion
+		}));
+	}
+	return {
+		conflicts,
+		required
+	};
+}
+/**
+* The required route decorator groups of the application (RFC 0001): what every route-like target
+* of another extension (a gateway, a GraphQL root field) must decide, exactly as HTTP routes must.
+* A target without a decision of a returned group is **ZNIGHT023**, reported by the caller.
+*
+* `applied` are the route metadata entries the caller read on its own targets
+* ({@link readRouteMeta}): they make decorators known even when the compiler has no
+* `definitionsOf`, and refine how flags are suggested. Inconsistent definitions are left out and
+* not reported here: the http extension reports them (ZNIGHT005) once.
+*
+* ```ts
+* validate(ctx) {
+*   const required = requiredRouteGroups(ctx, ctx.stored.flatMap(gateway => gateway.meta))
+*   for (const gateway of ctx.stored)
+*     for (const group of required)
+*       if (!gateway.meta.some(entry => entry.group === group.group))
+*         ctx.report({ code: 'ZNIGHT023', severity: 'error', message: `${gateway.name} has no "${group.group}" decision`,
+*           location: gateway.location, hints: [`Add ${group.suggestion} to ${gateway.name}`] })
+* }
+* ```
+*/
+function requiredRouteGroups(ctx, applied = []) {
+	return analyzeRouteGroups(ctx, applied).required;
+}
+function describeOptions(entry) {
+	const group = entry.group === entry.key ? "no group" : `group "${entry.group}"`;
+	return entry.required ? `${group}, required` : group;
+}
+// src/compiler/validate.ts
+/** Validates the routes of every controller. */
+function validateHttp(ctx) {
+	const controllers = [...ctx.stored].sort((a, b) => compareStrings(a.token, b.token));
+	const registered = /* @__PURE__ */ new Map();
+	for (const controller of controllers) {
+		const baseIssue = checkRoutePath(controller.rawBasePath);
+		if (baseIssue !== void 0) {
+			invalidRoute(ctx, controller.pathLocation, `Invalid base path ${JSON.stringify(controller.rawBasePath)} of ${controller.displayName}: ${baseIssue.message}`, GRAMMAR_HINTS);
+			continue;
+		}
+		for (const route of controller.routes) {
+			const where = `${controller.displayName}.${route.handler}`;
+			const ownIssue = checkRoutePath(route.rawPath);
+			const issue = ownIssue ?? checkRoutePath(route.fullPath);
+			if (issue !== void 0) {
+				const path = ownIssue === void 0 ? route.fullPath : route.rawPath;
+				invalidRoute(ctx, route.pathLocation, `Invalid route path ${JSON.stringify(path)} of ${where}: ${issue.message}`, GRAMMAR_HINTS);
+				continue;
+			}
+			const parsed = parseRoutePath(route.fullPath);
+			checkParams(ctx, route, parsed, where);
+			const key = `${route.method} ${parsed.shape}`;
+			const previous = registered.get(key);
+			if (previous === void 0) {
+				registered.set(key, {
+					where,
+					route
+				});
+				continue;
+			}
+			ctx.report({
+				code: Codes.InvalidRoute,
+				severity: "error",
+				message: `Duplicate route ${route.method} ${route.fullPath}: ${where} conflicts with ${previous.where} (${previous.route.method} ${previous.route.fullPath})`,
+				location: route.location,
+				hints: ["Two routes with the same method and the same path shape (parameter names aside) cannot coexist"],
+				related: [{
+					message: `${previous.where} is declared here`,
+					location: previous.route.location
+				}]
+			});
+		}
+	}
+	validateDecisions(ctx, controllers);
+}
+/** Every route metadata entry of the controllers: controller entries, then route entries. */
+function* appliedEntries(controllers) {
+	for (const controller of controllers) {
+		yield* controller.meta;
+		for (const route of controller.routes) yield* route.meta;
+	}
+}
+/**
+* Route decorator groups (RFC 0001 §5.1): every definition of a key uses the same options and the
+* decorators of a group agree on `required` (ZNIGHT005, at the second definition); every route has
+* a decision of every required group, its own or its controller's (ZNIGHT023).
+*/
+function validateDecisions(ctx, controllers) {
+	const { conflicts, required } = analyzeRouteGroups(ctx, appliedEntries(controllers));
+	for (const conflict of conflicts) ctx.report(conflict);
 	if (required.length === 0) return;
 	for (const controller of controllers) {
 		const controllerGroups = new Set(controller.meta.map((entry) => entry.group));
@@ -2106,18 +2198,15 @@ function validateDecisions(ctx, controllers) {
 			const decided = /* @__PURE__ */ new Set([...controllerGroups, ...route.meta.map((entry) => entry.group)]);
 			for (const group of required) {
 				if (decided.has(group.group)) continue;
-				const inOrder = [...members.get(group.group) ?? [group]].sort((a, b) => compareStrings(a.definition.file, b.definition.file) || a.definition.start - b.definition.start);
-				const decorators = inOrder.map((definition) => `@${definition.name}(${definition.flag ? "" : "..."})`);
-				const listed = decorators.length === 1 ? decorators[0] : `${decorators.slice(0, -1).join(", ")} or ${decorators.at(-1)}`;
 				ctx.report({
 					code: Codes.MissingRouteDecision,
 					severity: "error",
 					message: `Route ${route.method} ${route.fullPath} (${controller.displayName}.${route.handler}) has no "${group.group}" decision`,
 					location: route.location,
-					hints: [`Add ${listed} to the route or to ${controller.displayName}`],
+					hints: [`Add ${group.suggestion} to the route or to ${controller.displayName}`],
 					related: [{
 						message: `The "${group.group}" group is required`,
-						location: (inOrder[0] ?? group).definition
+						location: firstDefinition(group)
 					}, {
 						message: `${controller.displayName} is declared here`,
 						location: controller.location
@@ -2127,9 +2216,9 @@ function validateDecisions(ctx, controllers) {
 		}
 	}
 }
-function describeOptions(entry) {
-	const group = entry.group === entry.key ? "no group" : `group "${entry.group}"`;
-	return entry.required ? `${group}, required` : group;
+/** Where the first decorator of a group (source order) is defined. */
+function firstDefinition(group) {
+	return group.decorators[0].definition;
 }
 const GRAMMAR_HINTS = ["Paths are made of static segments (letters, digits and - . _ ~ ! $ & ' + , ; = @), :name parameters and a trailing * wildcard"];
 /** `:param` of the path ↔ `@Param('name')` parameters of the handler. */
@@ -2244,6 +2333,6 @@ const http = Object.freeze({
 	validate: validateHttp,
 	generate: generateHttp
 });
-export { http as default };
+export { http as default, effectiveRouteMeta, readRouteMeta, requiredRouteGroups };
 
 //# sourceMappingURL=compiler.mjs.map