@nestia/sdk 14.0.1 → 14.0.2

package/src/analyses/ImportAnalyzer.ts

@@ -1,6 +1,15 @@
 import { IReflectImport } from "../structures/IReflectImport";
 import { MapUtil } from "../utils/MapUtil";
 
+/**
+ * Helpers for the import lists of routes.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace merges the imports collected for one route and keeps a removal notice for the old analysis entry.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The merge is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportAnalyzer 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 ImportAnalyzer {
   /**
    * @deprecated Removed in the Go-migration cycle. Import metadata is now
@@ -10,6 +19,11 @@ export namespace ImportAnalyzer {
    *   `ts.SourceFile` to derive imports should read the metadata delivered
    *   through `Reflect.getMetadata("nestia/OperationMetadata", …)` instead. See
    *   `packages/core/MIGRATION.md`.
+   * @evidence contracts/common.md#principled-implementation The function exists only to give an actionable error to a caller of the removed API, and always throws.
+   * @evidence contracts/common.md#clear-and-simple-design One statement.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reports the removal instead of failing later with a missing function.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the replacement.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportAnalyzer.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 = (): never => {
     throw new Error(
@@ -19,6 +33,17 @@ export namespace ImportAnalyzer {
     );
   };
 
+  /**
+   * Merges import records by file: namespace imports and default imports are
+   * deduplicated and sorted, and the named elements of every import of a file
+   * are combined with their aliases.
+   *
+   * @evidence contracts/common.md#principled-implementation Imports are grouped by file, each group emits its namespace imports, default imports, and one element list with an alias map for renamed elements, so the same file is imported once per kind.
+   * @evidence contracts/common.md#clear-and-simple-design One function over one group merger.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The merge follows the import records, with no file special-cased.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the grouping and the merging.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ImportAnalyzer.merge 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 merge = (imports: IReflectImport[]): IReflectImport[] => {
     // group by files
     const fileGroups: Map<string, IReflectImport[]> = new Map();

package/src/analyses/ParameterNameAnalyzer.ts

@@ -2,7 +2,25 @@ import { NamingConvention } from "@typia/utils";
 
 import { StringUtil } from "../utils/StringUtil";
 
+/**
+ * Gives names to parameters that declare none, such as destructured ones.
+ *
+ * @evidence contracts/common.md#principled-implementation A missing name is derived from the field, camel-cased when it is not an identifier, or from the category, and then made unique against the names already taken.
+ * @evidence contracts/common.md#clear-and-simple-design One function, one record type, and one private candidate rule.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is generic.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ParameterNameAnalyzer 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 ParameterNameAnalyzer {
+  /**
+   * A parameter to name: its current name, its category, and an optional field.
+   *
+   * @evidence contracts/common.md#principled-implementation The three members are the inputs of the naming rule.
+   * @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 ParameterNameAnalyzer.IParameter 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 IParameter {
     name: string;
     category: string;
@@ -20,6 +38,12 @@ export namespace ParameterNameAnalyzer {
    * dropped in camel case, otherwise its category, such as `body` or `query`.
    * The name yields to every other parameter's, which are the user's and are
    * kept.
+   *
+   * @evidence contracts/common.md#principled-implementation The names in use are collected first, and each new name is escaped against them with underscores and added, so the result has no duplicates.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Existing names are never changed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the rule.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ParameterNameAnalyzer.name 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 name = <T extends IParameter>(parameters: T[]): T[] => {
     const taken: string[] = parameters

package/src/analyses/PathAnalyzer.ts

@@ -1,11 +1,27 @@
 import { RequestMethod } from "@nestjs/common";
 import { Token, parse } from "path-to-regexp";
 
+/**
+ * Helpers for route paths: joining, prefixing, and reading their parameters the
+ * way the router does.
+ *
+ * @evidence contracts/common.md#principled-implementation Paths are parsed by `path-to-regexp` after Fastify colon escapes are converted, so the parameters and literals are those the server reads.
+ * @evidence contracts/common.md#clear-and-simple-design Several small functions over one tokenizer and one parser.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The router's own grammar decides, and no path is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace PathAnalyzer {
   /**
    * The route paths joined as the router joins them: one `/` between them, and
    * none doubled. A route path is router syntax, never a file path, so a
    * backslash stays the escape of the character after it (`items\\:batchGet`).
+   *
+   * @evidence contracts/common.md#principled-implementation The parts are joined, split on slashes, and empty segments are dropped, so any number of slashes at the boundaries collapses.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It applies to every input.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result form.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.join interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const join = (...args: string[]) =>
     "/" +
@@ -15,6 +31,16 @@ export namespace PathAnalyzer {
       .filter((str) => str.length !== 0)
       .join("/");
 
+  /**
+   * Joins a path with the global prefix, unless the route is excluded from the
+   * prefix.
+   *
+   * @evidence contracts/common.md#principled-implementation The exclusion list is matched by method and by exact path or pattern, as NestJS does, and an excluded route is joined with an empty prefix.
+   * @evidence contracts/common.md#clear-and-simple-design One function delegating the exclusion test to a private helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The exclusion rule is NestJS's.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the exclusion.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.joinWithGlobalPrefix interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const joinWithGlobalPrefix = (props: {
     globalPrefix: string;
     exclude: IGlobalPrefixExclude[] | undefined;
@@ -33,20 +59,15 @@ export namespace PathAnalyzer {
       props.path,
     );
 
-  export const escape = (str: string): string | null => {
-    const args = _Parse(str);
-    if (args === null) return null;
-    return (
-      "/" +
-      args
-        .map((arg) => (arg.type === "param" ? `:${arg.value}` : arg.value))
-        .join("/")
-    );
-  };
-
   /**
    * Whether a route path holds a wildcard: a `*` not escaped as the literal
    * character (`\\*`), which a route path may hold since #1713.
+   *
+   * @evidence contracts/common.md#principled-implementation A star preceded by a backslash is a literal, so the test looks for a star at the start or after a non-backslash character.
+   * @evidence contracts/common.md#clear-and-simple-design One regular expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the router's escaping rule.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the escaped case.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.wildcard interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const wildcard = (str: string): boolean => /(^|[^\\])\*/.test(str);
 
@@ -56,6 +77,12 @@ export namespace PathAnalyzer {
    * and `/range/:from-:to` holds two parameters parted by `-`. Every generator
    * that writes a path with its parameters filled in reads it from here, never
    * by splitting the text at `:` or `/`. `null` for a path it cannot parse.
+   *
+   * @evidence contracts/common.md#principled-implementation Tokens come from `path-to-regexp`, so text next to a parameter in one segment, such as `/files/:id.json`, is kept in place, adjacent literals merge, and an unnamed parameter makes the path unreadable.
+   * @evidence contracts/common.md#clear-and-simple-design One function over the tokenizer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The grammar is the router's.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result and why generators use it.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.segments interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const segments = (str: string): ISegment[] | null => {
     const tokens: Token[] | null = _Tokenize(str);
@@ -81,6 +108,12 @@ export namespace PathAnalyzer {
   /**
    * The path in OpenAPI's template syntax, each parameter written `{name}`:
    * `/files/:id.json` is `/files/{id}.json`.
+   *
+   * @evidence contracts/common.md#principled-implementation The segments are joined with literals verbatim and parameters in braces.
+   * @evidence contracts/common.md#clear-and-simple-design One expression over `segments`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the same segmenter as the SDK generator.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the fallback.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.toOpenApi interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const toOpenApi = (str: string): string => {
     const list: ISegment[] | null = segments(str);
@@ -91,10 +124,29 @@ export namespace PathAnalyzer {
           .join("");
   };
 
+  /**
+   * A segment of a path: literal text or a named parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation The union is discriminated by `type`, so a consumer handles each case once.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member union.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the two cases.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.ISegment interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export type ISegment =
     | { type: "literal"; value: string }
     | { type: "param"; name: string };
 
+  /**
+   * Returns the names of the parameters of a path, or `null` when the path
+   * cannot be parsed.
+   *
+   * @evidence contracts/common.md#principled-implementation The parsed arguments are filtered to the parameters, and an empty parameter name makes the path unreadable.
+   * @evidence contracts/common.md#clear-and-simple-design One filter over the private parser.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The grammar is the router's.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation PathAnalyzer.parameters interprets router protocol paths; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const parameters = (str: string): string[] | null => {
     const args = _Parse(str);
     if (args === null) return null;

package/src/analyses/ReflectControllerAnalyzer.ts

@@ -18,7 +18,26 @@ 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;
@@ -27,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 (

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;
@@ -135,7 +157,7 @@ export namespace ReflectHttpOperationAnalyzer {
         // 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

@@ -11,7 +11,26 @@ 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;
@@ -20,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);

package/src/analyses/ReflectHttpOperationResponseAnalyzer.ts

@@ -14,7 +14,26 @@ import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUti
 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;
@@ -24,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 => {

package/src/analyses/ReflectMcpOperationAnalyzer.ts

@@ -9,7 +9,26 @@ import { IReflectMcpOperationParameter } from "../structures/IReflectMcpOperatio
 import { ImportAnalyzer } from "./ImportAnalyzer";
 import { ParameterNameAnalyzer } from "./ParameterNameAnalyzer";
 
+/**
+ * Reflects an `@McpRoute` method into a tool operation.
+ *
+ * @evidence contracts/common.md#principled-implementation The tool definition comes from the route metadata, the single params parameter is matched with its compile-time type, and combinations with HTTP or WebSocket decorators and extra parameters are errors.
+ * @evidence contracts/common.md#clear-and-simple-design One public function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The rules follow the decorator contract.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectMcpOperationAnalyzer 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 ReflectMcpOperationAnalyzer {
+  /**
+   * The input of the MCP operation analysis: the project, the controller, the
+   * method, and its metadata.
+   *
+   * @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 ReflectMcpOperationAnalyzer.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: IReflectController;
@@ -18,6 +37,16 @@ export namespace ReflectMcpOperationAnalyzer {
     metadata: IOperationMetadata;
   }
 
+  /**
+   * Returns the tool operation of a method, or `null` when the method is not an
+   * MCP route or has errors.
+   *
+   * @evidence contracts/common.md#principled-implementation The method is an MCP route when it carries the route metadata; at most one params parameter is allowed and the function may have at most one argument; the return type and imports come from the metadata.
+   * @evidence contracts/common.md#clear-and-simple-design One function that collects errors once and reports them together.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rules follow the decorator contract.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the null result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectMcpOperationAnalyzer.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: IProps): IReflectMcpOperation | null => {
     const route:
       | {
@@ -62,7 +91,7 @@ export namespace ReflectMcpOperationAnalyzer {
 
     const imports: IReflectImport[] = [];
     const declared: IReflectMcpOperationParameter[] = preconfigured
-      .map((p) => {
+      .map((p): IReflectMcpOperationParameter | null => {
         const matched: IOperationMetadata.IParameter | undefined =
           ctx.metadata.parameters.find(
             (m: IOperationMetadata.IParameter) => p.index === m.index,
@@ -85,6 +114,7 @@ export namespace ReflectMcpOperationAnalyzer {
           name: matched.name,
           index: p.index,
           type: matched.type,
+          metadata: matched.primitive,
           imports: matched.imports,
           description: matched.description,
           jsDocTags: matched.jsDocTags,
@@ -120,6 +150,7 @@ export namespace ReflectMcpOperationAnalyzer {
       function: ctx.function,
       parameters,
       returnType: ctx.metadata.success?.type ?? null,
+      returnMetadata: ctx.metadata.success?.primitive,
       imports: ImportAnalyzer.merge(imports),
       description: ctx.metadata.description ?? null,
       jsDocTags: ctx.metadata.jsDocTags,

package/src/analyses/ReflectMetadataAnalyzer.ts

@@ -4,7 +4,26 @@ import { VersionValue } from "@nestjs/common/interfaces";
 
 import { SecurityAnalyzer } from "./SecurityAnalyzer";
 
+/**
+ * Reads the NestJS and Swagger metadata of a class or method.
+ *
+ * @evidence contracts/common.md#principled-implementation The functions read the reflect metadata keys that Nest and `@nestjs/swagger` define and normalize them into arrays.
+ * @evidence contracts/common.md#clear-and-simple-design Four small readers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts They read only public metadata keys.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectMetadataAnalyzer 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 ReflectMetadataAnalyzer {
+  /**
+   * Returns the path list of a controller or route: a string is a one-element
+   * list and an empty list is one empty path.
+   *
+   * @evidence contracts/common.md#principled-implementation Nest stores a path as a string or an array, and an empty array means the root path, so the result is never empty.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It normalizes without changing paths.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the normalization.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectMetadataAnalyzer.paths 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 paths = (target: Function): string[] => {
     const value: string | string[] = Reflect.getMetadata(PATH_METADATA, target);
     if (typeof value === "string") return [value];
@@ -12,6 +31,15 @@ export namespace ReflectMetadataAnalyzer {
     else return value;
   };
 
+  /**
+   * Returns the `@ApiExtension` values of a target.
+   *
+   * @evidence contracts/common.md#principled-implementation The metadata is returned as recorded, and an absent value is an empty object.
+   * @evidence contracts/common.md#clear-and-simple-design One read.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the Swagger metadata key.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectMetadataAnalyzer.extensions 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 extensions = (value: any): Record<string, any> => {
     const entire: Record<string, any>[] | undefined = Reflect.getMetadata(
       "swagger/apiExtension",
@@ -20,6 +48,15 @@ export namespace ReflectMetadataAnalyzer {
     return entire ?? {};
   };
 
+  /**
+   * Returns the deduplicated security requirements of a target.
+   *
+   * @evidence contracts/common.md#principled-implementation The `@ApiSecurity` metadata is merged by `SecurityAnalyzer.merge`, and an absent value is an empty list.
+   * @evidence contracts/common.md#clear-and-simple-design One read and one merge.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the Swagger metadata key.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectMetadataAnalyzer.securities 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 securities = (value: any): Record<string, string[]>[] => {
     const entire: Record<string, string[]>[] | undefined = Reflect.getMetadata(
       "swagger/apiSecurity",
@@ -28,6 +65,16 @@ export namespace ReflectMetadataAnalyzer {
     return entire ? SecurityAnalyzer.merge(...entire) : [];
   };
 
+  /**
+   * Returns the version list of a target, or `undefined` when it is
+   * unversioned.
+   *
+   * @evidence contracts/common.md#principled-implementation A single version becomes a one-element list, and an absent value stays absent so callers can tell unversioned from versioned.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads Nest's version metadata.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the three cases.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation ReflectMetadataAnalyzer.versions 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 versions = (
     target: any,
   ): Array<string | typeof VERSION_NEUTRAL> | undefined => {