@nestia/sdk 14.0.0 → 14.0.2

package/src/analyses/ReflectControllerAnalyzer.ts

@@ -12,12 +12,32 @@ import { IReflectHttpOperation } from "../structures/IReflectHttpOperation";
 import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
 import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
 import { ArrayUtil } from "../utils/ArrayUtil";
+import { PathAnalyzer } from "./PathAnalyzer";
 import { ReflectHttpOperationAnalyzer } from "./ReflectHttpOperationAnalyzer";
 import { ReflectMcpOperationAnalyzer } from "./ReflectMcpOperationAnalyzer";
 import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
 import { ReflectWebSocketOperationAnalyzer } from "./ReflectWebSocketOperationAnalyzer";
 
+/**
+ * Reflects a NestJS controller class into an operation list.
+ *
+ * @evidence contracts/common.md#principled-implementation A controller is recognized by Nest's own path, host, and scope metadata, its methods are visited along the prototype chain with a subclass method hiding an inherited one, and each method is classified as MCP, WebSocket, or HTTP.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and one prototype walker.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The recognition uses the metadata Nest writes, and no class name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectControllerAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ReflectControllerAnalyzer {
+  /**
+   * The input of the controller analysis: the project, the controller, and a
+   * set of visited functions.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds what one analysis needs and the shared error lists live in the project.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectControllerAnalyzer.IProps analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IProps {
     project: Omit<INestiaProject, "config">;
     controller: INestiaSdkInput.IController;
@@ -26,6 +46,19 @@ export namespace ReflectControllerAnalyzer {
   /* ---------------------------------------------------------
     CONTROLLER
   --------------------------------------------------------- */
+  /**
+   * Returns the reflected controller with its operations, or `null` for a class
+   * that is not a controller.
+   *
+   * Wildcard controller paths are dropped with a warning, and methods marked
+   * `@ignore` are skipped.
+   *
+   * @evidence contracts/common.md#principled-implementation The metadata keys of the class decide whether it is a controller, every own and inherited method with operation metadata is offered to the MCP, WebSocket, and HTTP analyzers in that order, and the first analyzer that accepts it owns it.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The order of the analyzers is fixed by the mutual exclusion of the decorators.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the null result, the warning, and the ignore tag.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectControllerAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (props: IProps): IReflectController | null => {
     // MUST BE TYPE OF A CREATOR WHO HAS THE CONSTRUCTOR
     if (
@@ -46,7 +79,7 @@ export namespace ReflectControllerAnalyzer {
       prefixes: props.controller.prefixes,
       paths: ReflectMetadataAnalyzer.paths(props.controller.class).filter(
         (str) => {
-          if (str.includes("*") === true) {
+          if (PathAnalyzer.wildcard(str)) {
             props.project.warnings.push({
               file: props.controller.location,
               class: props.controller.class.name,

package/src/analyses/ReflectHttpOperationAnalyzer.ts

@@ -16,7 +16,26 @@ import { ReflectHttpOperationParameterAnalyzer } from "./ReflectHttpOperationPar
 import { ReflectHttpOperationResponseAnalyzer } from "./ReflectHttpOperationResponseAnalyzer";
 import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
 
+/**
+ * Reflects an HTTP route method into an operation.
+ *
+ * @evidence contracts/common.md#principled-implementation The method, the path list, the parameters, the success response, the exceptions, the imports, the security, and the extensions are composed from Nest's metadata and the compile-time metadata, and the path parameters of the decorator are checked against the parameter decorators.
+ * @evidence contracts/common.md#clear-and-simple-design One public function over the parameter, response, and exception analyzers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The checks follow the decorators and no route is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ReflectHttpOperationAnalyzer {
+  /**
+   * The input of the HTTP operation analysis: the project, the controller, the
+   * method, and its compile-time metadata.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds the reflected function and the metadata the transform attached to it.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationAnalyzer.IProps analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IProps {
     project: Omit<INestiaProject, "config"> &
       Partial<Pick<INestiaProject, "config">>;
@@ -25,6 +44,16 @@ export namespace ReflectHttpOperationAnalyzer {
     name: string;
     metadata: IOperationMetadata;
   }
+  /**
+   * Returns the reflected HTTP operation, or `null` when the method is not a
+   * route or has errors, which are pushed to the project.
+   *
+   * @evidence contracts/common.md#principled-implementation A method is a route when it has Nest's path and method metadata; `ALL` is treated as POST and OPTIONS is skipped; a mismatch between the path parameters and the parameter decorators is an error.
+   * @evidence contracts/common.md#clear-and-simple-design One function that collects errors and returns nothing when there is one.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rules follow the HTTP semantics of the decorators.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the null result and the collected errors.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (props: IProps): IReflectHttpOperation | null => {
     if (
       ArrayUtil.has(
@@ -49,9 +78,8 @@ export namespace ReflectHttpOperationAnalyzer {
         functionName: props.name,
         errors,
       });
-    const success: IReflectHttpOperationSuccess | null = (() => {
-      const localErrors: IReflectOperationError[] = [];
-      const success = ReflectHttpOperationResponseAnalyzer.analyze({
+    const success: IReflectHttpOperationSuccess | null =
+      ReflectHttpOperationResponseAnalyzer.analyze({
         controller: props.controller,
         function: props.function,
         functionName: props.name,
@@ -59,12 +87,6 @@ export namespace ReflectHttpOperationAnalyzer {
         metadata: props.metadata,
         errors,
       });
-      if (localErrors.length) {
-        errors.push(...localErrors);
-        return null;
-      }
-      return success;
-    })();
     if (errors.length) {
       props.project.errors.push(...errors);
       return null;
@@ -77,7 +99,7 @@ export namespace ReflectHttpOperationAnalyzer {
       name: props.name,
       method: method === "ALL" ? "POST" : method,
       paths: ReflectMetadataAnalyzer.paths(props.function).filter((str) => {
-        if (str.includes("*") === true) {
+        if (PathAnalyzer.wildcard(str)) {
           props.project.warnings.push({
             file: props.controller.file,
             class: props.controller.class.name,
@@ -117,8 +139,8 @@ export namespace ReflectHttpOperationAnalyzer {
       jsDocTags: props.metadata.jsDocTags,
       operationId: props.metadata.jsDocTags
         .find(({ name }) => name === "operationId")
-        ?.text?.[0]?.text.split(" ")[0]
-        ?.trim(),
+        ?.text?.[0]?.text.trim()
+        .split(/\s+/)[0],
       extensions: ReflectMetadataAnalyzer.extensions(props.function),
     };
 
@@ -130,12 +152,12 @@ export namespace ReflectHttpOperationAnalyzer {
           controllerLocation,
           metaLocation,
         );
-        if (location.includes("*")) continue;
+        if (PathAnalyzer.wildcard(location)) continue;
 
         // LIST UP PARAMETERS
         const binded: string[] | null = PathAnalyzer.parameters(location);
         if (binded === null) {
-          props.project.errors.push({
+          errors.push({
             file: props.controller.file,
             class: props.controller.class.name,
             function: props.name,

package/src/analyses/ReflectHttpOperationExceptionAnalyzer.ts

@@ -6,7 +6,26 @@ import { IReflectController } from "../structures/IReflectController";
 import { IReflectHttpOperationException } from "../structures/IReflectHttpOperationException";
 import { IReflectOperationError } from "../structures/IReflectOperationError";
 
+/**
+ * Reflects the `@TypedException` declarations of a method.
+ *
+ * @evidence contracts/common.md#principled-implementation The declarations are read in declaration order and matched by position with the exception types the transform recorded.
+ * @evidence contracts/common.md#clear-and-simple-design One public function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The matching is by position because both lists are produced in declaration order.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationExceptionAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ReflectHttpOperationExceptionAnalyzer {
+  /**
+   * The input of the exception analysis: the controller, the method, its name,
+   * the HTTP method, the metadata, and the error list.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds what the analysis needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationExceptionAnalyzer.IContext analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IContext {
     controller: IReflectController;
     function: Function;
@@ -15,6 +34,18 @@ export namespace ReflectHttpOperationExceptionAnalyzer {
     metadata: IOperationMetadata;
     errors: IReflectOperationError[];
   }
+  /**
+   * Returns the exceptions of a method by status.
+   *
+   * A declaration without a matching type, or with an unreadable one, is an
+   * error.
+   *
+   * @evidence contracts/common.md#principled-implementation Decorators apply bottom-up, so the metadata array is reversed to declaration order before it is paired with the transform's exception list, and the result is keyed by status, so the last declaration of a status wins.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The pairing follows the documented order, and every mismatch is reported.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the matching and the errors.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationExceptionAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (
     ctx: IContext,
   ): Record<string, IReflectHttpOperationException> => {

package/src/analyses/ReflectHttpOperationParameterAnalyzer.ts

@@ -2,22 +2,35 @@ import { SwaggerExample } from "@nestia/core";
 import { ROUTE_ARGS_METADATA } from "@nestjs/common/constants";
 import { RouteParamtypes } from "@nestjs/common/enums/route-paramtypes.enum";
 
-import {
-  HttpFormDataProgrammer,
-  HttpHeadersProgrammer,
-  HttpParameterProgrammer,
-  HttpQueryProgrammer,
-  JsonMetadataFactory,
-} from "../internal/legacy";
+import { JsonMetadataFactory } from "../internal/legacy";
 import { IOperationMetadata } from "../structures/IOperationMetadata";
 import { IReflectController } from "../structures/IReflectController";
 import { IReflectHttpOperationParameter } from "../structures/IReflectHttpOperationParameter";
 import { IReflectOperationError } from "../structures/IReflectOperationError";
-import { HttpHeadersValidator } from "../validators/HttpHeadersValidator";
-import { HttpQueryValidator } from "../validators/HttpQueryValidator";
 import { TextPlainValidator } from "../validators/TextPlainValidator";
+import { ParameterNameAnalyzer } from "./ParameterNameAnalyzer";
+import { SwaggerExampleAnalyzer } from "./SwaggerExampleAnalyzer";
 
+/**
+ * Reflects the parameters of a route method.
+ *
+ * @evidence contracts/common.md#principled-implementation Nest's route argument metadata gives each parameter's category and position, the nestia decorators are recognized by the name of their factory function, the metadata of the transform gives the type, and the wire rules of the HTTP input are checked against it.
+ * @evidence contracts/common.md#clear-and-simple-design One public function with private classification and duplicate checks.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The recognition by factory name couples this package to the function names of `@nestia/core`, a contract between the two packages.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationParameterAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ReflectHttpOperationParameterAnalyzer {
+  /**
+   * The input of the parameter analysis: the controller, the method, its name,
+   * the HTTP method, the metadata, and the error list.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds what the analysis needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationParameterAnalyzer.IContext analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IContext {
     controller: IReflectController;
     function: Function;
@@ -26,6 +39,18 @@ export namespace ReflectHttpOperationParameterAnalyzer {
     metadata: IOperationMetadata;
     errors: IReflectOperationError[];
   }
+  /**
+   * Returns the parameters of a route method in position order.
+   *
+   * Contradictions, such as a body on GET, duplicated bodies or fields,
+   * unreadable types, and types the HTTP input cannot carry, are errors.
+   *
+   * @evidence contracts/common.md#principled-implementation Contradictions are collected first, each parameter is composed with the schema that matches its content type, its wire rules are checked, unnamed parameters are named, and duplicate keys between field parameters and objects are reported.
+   * @evidence contracts/common.md#clear-and-simple-design One function that gathers every error before returning.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Every rule follows the HTTP or NestJS contract, and a parameter that cannot be sent is an error, not silently dropped.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the errors.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationParameterAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (ctx: IContext): IReflectHttpOperationParameter[] => {
     const preconfigured: IReflectHttpOperationParameter.IPreconfigured[] =
       analyzePreconfigured(ctx);
@@ -89,7 +114,9 @@ export namespace ReflectHttpOperationParameterAnalyzer {
         preconfigured
           .filter((x) => x.category === "headers")
           .map((x) => x.field)
-          .filter((field) => field !== undefined),
+          .filter((field) => field !== undefined)
+          // NestJS reads `req.headers[name.toLowerCase()]`
+          .map((field) => field.toLowerCase()),
       ) === false
     )
       contradict(`Duplicated field names of headers are not allowed.`);
@@ -105,7 +132,7 @@ export namespace ReflectHttpOperationParameterAnalyzer {
     //----
     // COMPOSE PARAMETERS
     //----
-    const parameters: IReflectHttpOperationParameter[] = preconfigured
+    const declared: IReflectHttpOperationParameter[] = preconfigured
       .map((p): IReflectHttpOperationParameter | null => {
         // METADATA INFO
         const pErrorContents: Array<string | IOperationMetadata.IError> = [];
@@ -116,7 +143,8 @@ export namespace ReflectHttpOperationParameterAnalyzer {
             file: ctx.controller.file,
             class: ctx.controller.class.name,
             function: ctx.functionName,
-            from: `parameter ${matched ? JSON.stringify(matched.name) : `of ${p.index} th`}`,
+            // a destructured parameter has no name to report
+            from: `parameter ${matched?.name ? JSON.stringify(matched.name) : `of ${p.index} th`}`,
             contents: pErrorContents,
           });
           return null;
@@ -129,20 +157,31 @@ export namespace ReflectHttpOperationParameterAnalyzer {
           pErrorContents.push(`Failed to get the type info.`);
 
         // CONSIDER KIND
-        const schema: IOperationMetadata.ISchema | null = (() => {
+        const pipe = (() => {
           if (matched === undefined) return null;
-          const result =
-            p.category === "body" &&
+          return p.category === "body" &&
             (p.contentType === "application/json" || p.encrypted === true)
-              ? matched.primitive
-              : matched.resolved;
-          return result.success ? result.data : null;
+            ? matched.primitive
+            : matched.resolved;
         })();
+        const schema: IOperationMetadata.ISchema | null =
+          pipe?.success === true ? pipe.data : null;
+        // A type the metadata analysis could not read has no SDK or Swagger
+        // form; dropping the parameter would leave a function that cannot
+        // send what the route requires.
+        if (pipe?.success === false) pErrorContents.push(...pipe.errors);
         if (p.category === "body" && p.field !== undefined)
           pErrorContents.push(`@Body() must not have a field name.`);
         else if (p.category === "param" && p.field === undefined)
           pErrorContents.push(`@Param() must have a field name.`);
 
+        // The wire rules of the parameter's HTTP input: a type they reject
+        // cannot be carried as a query string, headers, a path segment, or a
+        // form, so the SDK would send garbage and the document would lie.
+        const rule: keyof IOperationMetadata.IHttpRules | null = httpRuleOf(p);
+        if (rule !== null && schema !== null)
+          pErrorContents.push(...(schema.http?.[rule] ?? []));
+
         if (pErrorContents.length) return report();
         else if (
           matched === undefined ||
@@ -150,6 +189,7 @@ export namespace ReflectHttpOperationParameterAnalyzer {
           schema === null
         )
           return null; // unreachable
+        const { http: _http, ...shape } = schema;
 
         const example: SwaggerExample.IData<any> | undefined = (
           Reflect.getMetadata(
@@ -167,12 +207,11 @@ export namespace ReflectHttpOperationParameterAnalyzer {
             field: p.field!,
             name: matched.name,
             type: matched.type,
-            validate: HttpParameterProgrammer.validate,
             description: matched.description,
             jsDocTags: matched.jsDocTags,
             example: example?.example,
-            examples: example?.examples,
-            ...schema,
+            examples: SwaggerExampleAnalyzer.examples(example),
+            ...shape,
           };
         else if (p.category === "query")
           return {
@@ -181,14 +220,11 @@ export namespace ReflectHttpOperationParameterAnalyzer {
             field: p.field ?? null,
             name: matched.name,
             type: matched.type,
-            validate: p.field
-              ? HttpQueryValidator.validate
-              : HttpQueryProgrammer.validate,
             description: matched.description,
             jsDocTags: matched.jsDocTags,
             example: example?.example,
-            examples: example?.examples,
-            ...schema,
+            examples: SwaggerExampleAnalyzer.examples(example),
+            ...shape,
           };
         else if (p.category === "headers")
           return {
@@ -197,14 +233,11 @@ export namespace ReflectHttpOperationParameterAnalyzer {
             field: p.field ?? null,
             name: matched.name,
             type: matched.type,
-            validate: p.field
-              ? HttpHeadersValidator.validate
-              : HttpHeadersProgrammer.validate,
             description: matched.description,
             jsDocTags: matched.jsDocTags,
             example: example?.example,
-            examples: example?.examples,
-            ...schema,
+            examples: SwaggerExampleAnalyzer.examples(example),
+            ...shape,
           };
         else if (p.category === "body")
           return {
@@ -217,16 +250,14 @@ export namespace ReflectHttpOperationParameterAnalyzer {
             validate:
               p.contentType === "application/json" || p.encrypted === true
                 ? JsonMetadataFactory.validate
-                : p.contentType === "application/x-www-form-urlencoded"
-                  ? HttpQueryProgrammer.validate
-                  : p.contentType === "multipart/form-data"
-                    ? HttpFormDataProgrammer.validate
-                    : TextPlainValidator.validate,
+                : p.contentType === "text/plain"
+                  ? TextPlainValidator.validate
+                  : undefined,
             description: matched.description,
             jsDocTags: matched.jsDocTags,
             example: example?.example,
-            examples: example?.examples,
-            ...schema,
+            examples: SwaggerExampleAnalyzer.examples(example),
+            ...shape,
           };
         else {
           pErrorContents.push(`Unknown kind of the parameter.`);
@@ -234,11 +265,93 @@ export namespace ReflectHttpOperationParameterAnalyzer {
         }
       })
       .filter((x): x is IReflectHttpOperationParameter => x !== null);
+    // a destructured parameter declares no name, so it is given one
+    const parameters: IReflectHttpOperationParameter[] =
+      ParameterNameAnalyzer.name(declared);
 
+    const duplicated: string[] = findDuplicatedKeys(parameters);
+    if (duplicated.length)
+      errors.push({
+        file: ctx.controller.file,
+        class: ctx.controller.class.name,
+        function: ctx.functionName,
+        from: "",
+        contents: duplicated,
+      });
     if (errors.length) ctx.errors.push(...errors);
     return parameters;
   };
 
+  /**
+   * The HTTP input rules a parameter's type must satisfy, or `null` for a JSON
+   * or text body, whose policies are checked on the TypeScript side.
+   *
+   * The rules are typia's, baked per parameter by the SDK transform (see
+   * `nestiaSDKHttpRules`), because only this analyzer knows the decorator. A
+   * typed decorator was already held to them by the core transform, so the
+   * verdict is only news for a vanilla `@Query()`, `@Headers()`, or `@Param()`,
+   * which no transform touches.
+   */
+  const httpRuleOf = (
+    p: IReflectHttpOperationParameter.IPreconfigured,
+  ): keyof IOperationMetadata.IHttpRules | null => {
+    if (p.category === "param") return "param";
+    else if (p.category === "query")
+      return p.field !== undefined ? "field" : "query";
+    else if (p.category === "headers")
+      return p.field !== undefined ? "field" : "headers";
+    else if (p.contentType === "application/x-www-form-urlencoded")
+      return "query";
+    else if (p.contentType === "multipart/form-data") return "formData";
+    return null;
+  };
+
+  /**
+   * Reports a query key or header both a field parameter and the object
+   * parameter of its category declare.
+   *
+   * On the wire they are one key: NestJS hands both parameters the same
+   * `req.query.keyword`, and header names match case-insensitively, as NestJS
+   * lowercases the name a `@Headers("X-Tenant")` reads. Documenting both lists
+   * one `name` + `in` pair twice, which OpenAPI forbids, and the SDK would ask
+   * its caller for the same key twice and send one of the two values. Like two
+   * field parameters of the same name, the declaration is contradictory.
+   */
+  const findDuplicatedKeys = (
+    parameters: IReflectHttpOperationParameter[],
+  ): string[] => {
+    const messages: string[] = [];
+    for (const [category, normalize, noun] of [
+      ["query", (key: string) => key, "Query key"],
+      ["headers", (key: string) => key.toLowerCase(), "Header"],
+    ] as const) {
+      const fields: Map<string, string> = new Map();
+      for (const p of parameters)
+        if (p.category === category && p.field !== null)
+          fields.set(normalize(p.field), p.field);
+      for (const p of parameters) {
+        if (p.category !== category || p.field !== null) continue;
+        for (const key of objectKeys(p)) {
+          const field: string | undefined = fields.get(normalize(key));
+          if (field !== undefined)
+            messages.push(
+              `${noun} ${JSON.stringify(field)} is declared both by a field parameter and by the ${category} object.`,
+            );
+        }
+      }
+    }
+    return messages;
+  };
+
+  /** Literal property keys of an object parameter's object type. */
+  const objectKeys = (p: IReflectHttpOperationParameter): string[] => {
+    const name: string | undefined = p.metadata.objects[0]?.name;
+    const object = p.components.objects.find((o) => o.name === name);
+    return (object?.properties ?? [])
+      .map((property) => property.key.constants[0]?.values[0]?.value)
+      .filter((key): key is string => typeof key === "string");
+  };
+
   const analyzePreconfigured = (
     props: IContext,
   ): IReflectHttpOperationParameter.IPreconfigured[] => {
@@ -263,9 +376,10 @@ export namespace ReflectHttpOperationParameterAnalyzer {
     const symbol: string = key.split(":")[0]!;
     if (symbol.indexOf("__custom") !== -1) return analyzeCustomParameter(param);
 
+    // the whole number: `RAW_BODY` is 12, which the first digit misread as 1
     const category:
       | IReflectHttpOperationParameter.IPreconfigured["category"]
-      | null = getNestParamType(Number(symbol[0]) as RouteParamtypes);
+      | null = getNestParamType(Number(symbol) as RouteParamtypes);
     if (category === null) return null;
     if (category === "body")
       return {

package/src/analyses/ReflectHttpOperationResponseAnalyzer.ts

@@ -5,19 +5,35 @@ import {
   INTERCEPTORS_METADATA,
 } from "@nestjs/common/constants";
 
-import {
-  HttpQueryProgrammer,
-  JsonMetadataFactory,
-  sizeOf,
-} from "../internal/legacy";
+import { JsonMetadataFactory, sizeOf } from "../internal/legacy";
 import { IOperationMetadata } from "../structures/IOperationMetadata";
 import { IReflectController } from "../structures/IReflectController";
 import { IReflectHttpOperationSuccess } from "../structures/IReflectHttpOperationSuccess";
 import { IReflectOperationError } from "../structures/IReflectOperationError";
 import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
 import { TextPlainValidator } from "../validators/TextPlainValidator";
+import { SwaggerExampleAnalyzer } from "./SwaggerExampleAnalyzer";
 
+/**
+ * Reflects the success response of a route method.
+ *
+ * @evidence contracts/common.md#principled-implementation The content type comes from the encryption and query interceptors, then the headers metadata, then the produces metadata, then the method default; the status comes from the HTTP code metadata or the method default; binary types skip the schema.
+ * @evidence contracts/common.md#clear-and-simple-design One public function with small private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The order follows how NestJS and nestia decorate a route.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationResponseAnalyzer analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace ReflectHttpOperationResponseAnalyzer {
+  /**
+   * The input of the response analysis: the controller, the method, its name,
+   * the HTTP method, the metadata, and the error list.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds what the analysis needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationResponseAnalyzer.IContext analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IContext {
     controller: IReflectController;
     function: Function;
@@ -27,6 +43,19 @@ export namespace ReflectHttpOperationResponseAnalyzer {
     errors: IReflectOperationError[];
   }
 
+  /**
+   * Returns the success response of a method, or `null` when it cannot be
+   * described; the reasons are pushed to the errors.
+   *
+   * A HEAD method must have no content type, and an unsupported content type is
+   * an error.
+   *
+   * @evidence contracts/common.md#principled-implementation The schema is the primitive form for JSON and the resolved form for other types, the validator depends on the content type, and the status defaults to 201 for POST and 200 otherwise.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The defaults are NestJS's.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the null result and the two errors.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectHttpOperationResponseAnalyzer.analyze analyzes reflected route metadata; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const analyze = (
     ctx: IContext,
   ): IReflectHttpOperationSuccess | null => {
@@ -102,7 +131,9 @@ export namespace ReflectHttpOperationResponseAnalyzer {
           : contentType === "application/json" || encrypted === true
             ? JsonMetadataFactory.validate
             : contentType === "application/x-www-form-urlencoded"
-              ? HttpQueryProgrammer.validate
+              ? // a typed query response, held to typia's query rules by the
+                // core transform
+                undefined
               : contentType === "text/plain"
                 ? TextPlainValidator.validate
                 : (next) =>
@@ -110,7 +141,7 @@ export namespace ReflectHttpOperationResponseAnalyzer {
                       ? ["HEAD method must not have any return value."]
                       : [],
       example: example?.example,
-      examples: example?.examples,
+      examples: SwaggerExampleAnalyzer.examples(example),
     };
   };