@nestia/sdk 14.0.0 → 14.0.2

package/src/structures/INestiaProject.ts

@@ -2,6 +2,16 @@ import { INestiaConfig } from "../INestiaConfig";
 import { INestiaSdkInput } from "./INestiaSdkInput";
 import { IReflectOperationError } from "./IReflectOperationError";
 
+/**
+ * The state of one generation: the configuration, the analyzed input, and the
+ * collected errors and warnings.
+ *
+ * @evidence contracts/common.md#principled-implementation The analyses append to the two lists and the generators run only when the error list is empty.
+ * @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; its members are named for their meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Configuration pathnames remain in INestiaConfig and controller source identities remain in INestiaSdkInput; this project record carries both unchanged without converting URL spelling into native identity.
+ */
 export interface INestiaProject {
   config: INestiaConfig;
   input: INestiaSdkInput;

package/src/structures/INestiaSdkInput.ts

@@ -1,6 +1,16 @@
 import { RequestMethod } from "@nestjs/common";
 import { VersionValue } from "@nestjs/common/interfaces";
 
+/**
+ * The analyzed input: the controllers, the global prefix with its exclusions,
+ * and the URI versioning options.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the common result of compiling sources and of reading a running application.
+ * @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; its members are named for their meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation Controller location is a native source pathname supplied by ConfigAnalyzer; prefixes, exclusions and versions are router protocol strings, not filesystem paths.
+ */
 export interface INestiaSdkInput {
   controllers: INestiaSdkInput.IController[];
   globalPrefix?: {
@@ -13,11 +23,31 @@ export interface INestiaSdkInput {
   };
 }
 export namespace INestiaSdkInput {
+  /**
+   * A controller class with its source file and the module prefixes it is
+   * mounted under.
+   *
+   * @evidence contracts/common.md#principled-implementation The three members are what the reflection needs to analyze one controller and to report its errors by file.
+   * @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; its members are named for their meaning.
+   * @evidence contracts/portability.md#os-neutral-implementation location carries the native source pathname resolved by ConfigAnalyzer, while prefixes are HTTP mount paths; the two representations are not normalized together.
+   */
   export interface IController {
     class: Function;
     location: string;
     prefixes: string[];
   }
+  /**
+   * A route excluded from the global prefix, by path, or by pattern, and
+   * optionally by request method.
+   *
+   * @evidence contracts/common.md#principled-implementation The members mirror NestJS's exclusion entry, so the same match decides here and in the server.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation INestiaSdkInput.IGlobalPrefixExclude describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IGlobalPrefixExclude {
     path: string;
     method?: RequestMethod;

package/src/structures/IOperationMetadata.ts

@@ -8,6 +8,16 @@ import { IJsDocTagInfo } from "typia";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * The compile-time metadata of an operation: its parameters, its success, its
+ * exceptions, its description, and its JSDoc tags.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is what the nestia transform serializes into the `OperationMetadata` decorator and the analyzers read back.
+ * @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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IOperationMetadata describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface IOperationMetadata {
   parameters: IOperationMetadata.IParameter[];
   success: IOperationMetadata.IResponse;
@@ -16,12 +26,32 @@ export interface IOperationMetadata {
   jsDocTags: IJsDocTagInfo[];
 }
 export namespace IOperationMetadata {
+  /**
+   * The metadata of a parameter: the response fields plus its name, position,
+   * description, and tags.
+   *
+   * @evidence contracts/common.md#principled-implementation A parameter has the type facts of a response and the identity facts of a declaration.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IOperationMetadata.IParameter describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IParameter extends IResponse {
     name: string;
     index: number;
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
   }
+  /**
+   * The metadata of a value: its reflected type, its imports, and its schemas
+   * in the primitive and the resolved forms.
+   *
+   * @evidence contracts/common.md#principled-implementation Each form is either a schema or the list of errors that made it unavailable, so an unreadable type is reported instead of dropped.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IOperationMetadata.IResponse describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IResponse {
     type: IReflectType | null;
     imports: IReflectImport[];
@@ -29,10 +59,63 @@ export namespace IOperationMetadata {
     resolved: ValidationPipe<ISchema, IError>;
   }
 
+  /**
+   * A schema: the components, the metadata, and the wire rule violations of the
+   * type.
+   *
+   * @evidence contracts/common.md#principled-implementation The components and the metadata describe the type and the HTTP rules record why it cannot travel as a query, a header, a path segment, or a form.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IOperationMetadata.ISchema describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface ISchema {
     components: IMetadataComponents;
     metadata: IMetadataSchema;
+
+    /**
+     * Violations of each HTTP input's wire rules, baked on the resolved schema
+     * of a route parameter only; the SDK picks the one its decorator selects.
+     */
+    http?: IHttpRules;
+  }
+
+  /**
+   * The violations of each HTTP input category's rules, which are typia's own
+   * validators except the path parameter rule typia keeps unexported and the
+   * one of a field-named `@Query("key")` or `@Headers("key")`.
+   *
+   * @evidence contracts/common.md#principled-implementation One list per input kind lets the parameter analysis pick the list that applies.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IOperationMetadata.IHttpRules describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
+  export interface IHttpRules {
+    /** A query object: `@TypedQuery()`, `@Query()`, `@TypedQuery.Body()`. */
+    query: IError[];
+
+    /** A headers object: `@TypedHeaders()`, `@Headers()`. */
+    headers: IError[];
+
+    /** A path parameter: `@TypedParam("key")`, `@Param("key")`. */
+    param: IError[];
+
+    /** One query key or header: `@Query("key")`, `@Headers("key")`. */
+    field: IError[];
+
+    /** A multipart body: `@TypedFormData.Body()`. */
+    formData: IError[];
   }
+  /**
+   * One analysis error: the name, the accessor of the member, and the messages.
+   *
+   * @evidence contracts/common.md#principled-implementation The three members identify where in a type the error is.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IOperationMetadata.IError describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IError {
     name: string;
     accessor: string | null;

package/src/structures/IReflectController.ts

@@ -4,6 +4,16 @@ import { IReflectHttpOperation } from "./IReflectHttpOperation";
 import { IReflectMcpOperation } from "./IReflectMcpOperation";
 import { IReflectWebSocketOperation } from "./IReflectWebSocketOperation";
 
+/**
+ * A reflected controller: its class, its file, its paths, prefixes, versions,
+ * security, tags, and operations.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the reflection result that the typed analysis consumes.
+ * @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; its members are named for their meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation file carries the controller source pathname supplied by ConfigAnalyzer; paths and prefixes retain Nest router spelling independently of native separators.
+ */
 export interface IReflectController {
   class: Function;
   prefixes: string[];

package/src/structures/IReflectHttpOperation.ts

@@ -6,6 +6,16 @@ import { IReflectHttpOperationParameter } from "./IReflectHttpOperationParameter
 import { IReflectHttpOperationSuccess } from "./IReflectHttpOperationSuccess";
 import { IReflectImport } from "./IReflectImport";
 
+/**
+ * A reflected HTTP operation: its function, name, method, paths, versions,
+ * parameters, success, exceptions, security, tags, imports, and description.
+ *
+ * @evidence contracts/common.md#principled-implementation The record joins Nest's runtime metadata with the compile-time metadata of the transform.
+ * @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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectHttpOperation describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface IReflectHttpOperation {
   protocol: "http";
   function: Function;

package/src/structures/IReflectHttpOperationException.ts

@@ -1,14 +1,29 @@
-import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
+import {
+  IMetadataComponents,
+  IMetadataSchema,
+  OpenApi,
+} from "@typia/interface";
 
 import { MetadataFactory } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * A reflected exception of an operation: its status, description, examples,
+ * type, metadata, components, and validator.
+ *
+ * @evidence contracts/common.md#principled-implementation The declaration fields come from `@TypedException` and the reflected fields from the transform.
+ * @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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectHttpOperationException describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface IReflectHttpOperationException {
   // BASIC PROPERTIES
   status: number | "2XX" | "3XX" | "4XX" | "5XX";
   description: string | null;
   example?: any;
-  examples?: Record<string, any>;
+  /** Named examples, as OpenAPI Example Objects. */
+  examples?: Record<string, OpenApi.IExample>;
 
   // REFLECTED PROPERTIES
   type: IReflectType;

package/src/structures/IReflectHttpOperationParameter.ts

@@ -2,17 +2,38 @@ import {
   IJsDocTagInfo,
   IMetadataComponents,
   IMetadataSchema,
+  OpenApi,
 } from "@typia/interface";
 
 import { MetadataFactory } from "../internal/legacy";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * A reflected parameter of an HTTP operation: a body, headers, a path
+ * parameter, or a query.
+ *
+ * @evidence contracts/common.md#principled-implementation The union is discriminated by `category`, with the fields each category needs, and a preconfigured form for what Nest's metadata alone gives.
+ * @evidence contracts/common.md#clear-and-simple-design A union of four records plus the preconfigured 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 states what the type describes; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectHttpOperationParameter describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export type IReflectHttpOperationParameter =
   | IReflectHttpOperationParameter.IBody
   | IReflectHttpOperationParameter.IHeaders
   | IReflectHttpOperationParameter.IParam
   | IReflectHttpOperationParameter.IQuery;
 export namespace IReflectHttpOperationParameter {
+  /**
+   * The reflected parameter of a body, with its content type and whether it is
+   * encrypted.
+   *
+   * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectHttpOperationParameter.IBody describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IBody extends IBase<"body"> {
     contentType:
       | "application/json"
@@ -21,12 +42,39 @@ export namespace IReflectHttpOperationParameter {
       | "text/plain";
     encrypted: boolean;
   }
+  /**
+   * The reflected parameter of the headers, as an object or as one field.
+   *
+   * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectHttpOperationParameter.IHeaders describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IHeaders extends IBase<"headers"> {
     field: string | null;
   }
+  /**
+   * The reflected parameter of a path parameter with its field name.
+   *
+   * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectHttpOperationParameter.IParam describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IParam extends IBase<"param"> {
     field: string;
   }
+  /**
+   * The reflected parameter of the query, as an object or as one field.
+   *
+   * @evidence contracts/common.md#principled-implementation The record extends the shared base with the members its category adds.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectHttpOperationParameter.IQuery describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IQuery extends IBase<"query"> {
     field: string | null;
   }
@@ -37,9 +85,15 @@ export namespace IReflectHttpOperationParameter {
     type: IReflectType;
     metadata: IMetadataSchema;
     components: IMetadataComponents;
-    validate: MetadataFactory.Validator;
+
+    /**
+     * SDK policy checked over the metadata, for a JSON or text body. An HTTP
+     * input's wire rules are typia's instead, baked beside its metadata.
+     */
+    validate?: MetadataFactory.Validator;
     example?: any;
-    examples?: Record<string, any>;
+    /** Named examples, as OpenAPI Example Objects. */
+    examples?: Record<string, OpenApi.IExample>;
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
   }

package/src/structures/IReflectHttpOperationSuccess.ts

@@ -1,9 +1,24 @@
-import { IMetadataComponents, IMetadataSchema } from "@typia/interface";
+import {
+  IMetadataComponents,
+  IMetadataSchema,
+  OpenApi,
+} from "@typia/interface";
 
 import { MetadataFactory } from "../internal/legacy";
 import { HttpResponseContentTypeUtil } from "../utils/HttpResponseContentTypeUtil";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * The reflected success response of an operation: its type, status, content
+ * type, whether it is binary or encrypted, its schema, validator, and
+ * examples.
+ *
+ * @evidence contracts/common.md#principled-implementation The record holds what the SDK and the Swagger generators need to describe the response.
+ * @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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectHttpOperationSuccess describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface IReflectHttpOperationSuccess {
   type: IReflectType;
   status: number;
@@ -12,7 +27,8 @@ export interface IReflectHttpOperationSuccess {
   encrypted: boolean;
   components: IMetadataComponents;
   metadata: IMetadataSchema;
-  validate: MetadataFactory.Validator;
+  validate?: MetadataFactory.Validator;
   example?: any;
-  examples?: Record<string, any>;
+  /** Named examples, as OpenAPI Example Objects. */
+  examples?: Record<string, OpenApi.IExample>;
 }

package/src/structures/IReflectImport.ts

@@ -1,3 +1,13 @@
+/**
+ * An import of a source file: its file, its namespace import, its default
+ * import, its named elements, and their aliases.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is one import declaration in a form that can be merged by file.
+ * @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; its members are named for their meaning.
+ * @evidence contracts/portability.md#os-neutral-implementation file carries the source identity emitted by the native import analyzer; ImportDictionary owns converting it to a relative slash-separated module specifier. Binding names and aliases are language identifiers.
+ */
 export interface IReflectImport {
   file: string;
   asterisk: string | null;

package/src/structures/IReflectMcpOperation.ts

@@ -1,5 +1,6 @@
 import { IJsDocTagInfo } from "typia";
 
+import { IOperationMetadata } from "./IOperationMetadata";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectMcpOperationParameter } from "./IReflectMcpOperationParameter";
 import { IReflectType } from "./IReflectType";
@@ -10,6 +11,12 @@ import { IReflectType } from "./IReflectType";
  * Produced by {@link ReflectMcpOperationAnalyzer.analyze}; consumed by
  * {@link TypedMcpRouteAnalyzer.analyze} to produce the final
  * {@link ITypedMcpRoute}.
+ *
+ * @evidence contracts/common.md#principled-implementation The record joins the route metadata of the decorator with the compile-time metadata.
+ * @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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectMcpOperation describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
  */
 export interface IReflectMcpOperation {
   protocol: "mcp";
@@ -23,12 +30,24 @@ export interface IReflectMcpOperation {
   function: Function;
   parameters: IReflectMcpOperationParameter[];
   returnType: IReflectType | null;
+  /** Native JSON return analysis; optional for source-only reflected inputs. */
+  returnMetadata?: IOperationMetadata.IResponse["primitive"];
   imports: IReflectImport[];
   description: string | null;
   jsDocTags: IJsDocTagInfo[];
 }
 
 export namespace IReflectMcpOperation {
+  /**
+   * The behavior hints of a tool: read-only, destructive, idempotent, and
+   * open-world.
+   *
+   * @evidence contracts/common.md#principled-implementation The four optional flags are the hints the MCP protocol defines.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectMcpOperation.IAnnotations describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IAnnotations {
     readOnlyHint?: boolean;
     destructiveHint?: boolean;

package/src/structures/IReflectMcpOperationParameter.ts

@@ -1,5 +1,6 @@
 import { IJsDocTagInfo } from "typia";
 
+import { IOperationMetadata } from "./IOperationMetadata";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectType } from "./IReflectType";
 
@@ -7,12 +8,20 @@ import { IReflectType } from "./IReflectType";
  * Parameter descriptor for an MCP tool method. Reflected from
  * `"nestia/McpRoute/Parameters"` metadata plus compile-time type information
  * collected by the nestia transformer.
+ *
+ * @evidence contracts/common.md#principled-implementation A tool has at most one parameter, and the record is what the SDK needs to type 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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectMcpOperationParameter describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
  */
 export interface IReflectMcpOperationParameter {
   category: "params";
   name: string;
   index: number;
   type: IReflectType;
+  /** Native JSON wire analysis, retained independently of the source import. */
+  metadata?: IOperationMetadata.IResponse["primitive"];
   imports: IReflectImport[];
   description: string | null;
   jsDocTags: IJsDocTagInfo[];

package/src/structures/IReflectOperationError.ts

@@ -2,6 +2,16 @@ import { IComparable } from "tstl";
 
 import { IOperationMetadata } from "../structures/IOperationMetadata";
 
+/**
+ * An error or warning of the reflection: the file, the class, the function, the
+ * origin, and the contents.
+ *
+ * @evidence contracts/common.md#principled-implementation The members locate a problem down to the part of a function, and the namespace's key orders errors by that location so a report groups them.
+ * @evidence contracts/common.md#clear-and-simple-design A record and one key class in its namespace.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior. The key class only compares fields.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the record locates.
+ * @evidence contracts/portability.md#os-neutral-implementation file carries the original native source identity for diagnostics; class, function and from identify declarations rather than filesystem components.
+ */
 export interface IReflectOperationError {
   file: string;
   class: string;
@@ -10,16 +20,35 @@ export interface IReflectOperationError {
   contents: Array<string | IOperationMetadata.IError>;
 }
 export namespace IReflectOperationError {
+  /**
+   * An ordering key of an error: file, then class, then function, then origin.
+   *
+   * @evidence contracts/common.md#principled-implementation The key implements the strict weak order over the four fields that tstl's tree map requires, with an absent value ordered as the empty string.
+   * @evidence contracts/common.md#clear-and-simple-design One class with one method.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It compares fields and holds no state beyond the error.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the order.
+   * @evidence contracts/portability.md#os-neutral-implementation The key retains supplied source file spelling and declaration identifiers. Ordering is lexical for diagnostic grouping without asserting filesystem case or symlink equivalence.
+   */
   export class Key implements Pick<IComparable<Key>, "less"> {
     public constructor(public readonly error: IReflectOperationError) {}
 
+    /**
+     * Returns whether this key orders before the other.
+     *
+     * @evidence contracts/common.md#principled-implementation The fields are compared in order and the first that differs decides, which is a lexicographic order.
+     * @evidence contracts/common.md#clear-and-simple-design One method of chained comparisons.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It compares only the four location fields.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+     * @evidence contracts/portability.md#os-neutral-implementation Comparison orders source identity strings and declaration fields lexically; it neither canonicalizes native paths nor treats ordering as filesystem equivalence.
+     */
     public less(obj: Key): boolean {
       if (this.error.file !== obj.error.file)
         return this.error.file < obj.error.file;
       else if (this.error.class !== obj.error.class)
         return this.error.class < obj.error.class;
-      else if (this.error.function !== obj.error.function)
-        return (this.error.function ?? "") < (obj.error.function ?? "");
+      const leftFunction = this.error.function ?? "";
+      const rightFunction = obj.error.function ?? "";
+      if (leftFunction !== rightFunction) return leftFunction < rightFunction;
       return (this.error.from ?? "") < (obj.error.from ?? "");
     }
   }

package/src/structures/IReflectType.ts

@@ -1,3 +1,12 @@
+/**
+ * A reflected type: its name and, for a generic, its type arguments.
+ *
+ * @evidence contracts/common.md#principled-implementation The name is the text the transform recorded and the arguments make the type recursive.
+ * @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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectType describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface IReflectType {
   name: string;
   typeArguments?: IReflectType[];

package/src/structures/IReflectWebSocketOperation.ts

@@ -4,6 +4,16 @@ import { IJsDocTagInfo } from "typia";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectWebSocketOperationParameter } from "./IReflectWebSocketOperationParameter";
 
+/**
+ * A reflected WebSocket operation: its name, paths, function, versions,
+ * parameters, and imports.
+ *
+ * @evidence contracts/common.md#principled-implementation The record joins the route metadata of the decorator with the compile-time metadata.
+ * @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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperation describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export interface IReflectWebSocketOperation {
   protocol: "websocket";
   name: string;

package/src/structures/IReflectWebSocketOperationParameter.ts

@@ -3,6 +3,16 @@ import { IJsDocTagInfo } from "typia";
 import { IReflectImport } from "./IReflectImport";
 import { IReflectType } from "./IReflectType";
 
+/**
+ * A parameter of a WebSocket operation: an acceptor, a driver, a header, a path
+ * parameter, or a query.
+ *
+ * @evidence contracts/common.md#principled-implementation The union is discriminated by `category`, and a preconfigured form carries what the decorators alone record.
+ * @evidence contracts/common.md#clear-and-simple-design A union of five records plus the preconfigured form.
+ * @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; its members are named for their meaning.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+ */
 export type IReflectWebSocketOperationParameter =
   | IReflectWebSocketOperationParameter.IAcceptor
   | IReflectWebSocketOperationParameter.IDriver
@@ -10,10 +20,55 @@ export type IReflectWebSocketOperationParameter =
   | IReflectWebSocketOperationParameter.IParam
   | IReflectWebSocketOperationParameter.IQuery;
 export namespace IReflectWebSocketOperationParameter {
+  /**
+   * The parameter category `acceptor` of a WebSocket operation.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias fixes the category of the shared base.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @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 category.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IAcceptor describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export type IAcceptor = IBase<"acceptor">;
+  /**
+   * The parameter category `driver` of a WebSocket operation.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias fixes the category of the shared base.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @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 category.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IDriver describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export type IDriver = IBase<"driver">;
+  /**
+   * The parameter category `header` of a WebSocket operation.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias fixes the category of the shared base.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @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 category.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IHeader describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export type IHeader = IBase<"header">;
+  /**
+   * The parameter category `query` of a WebSocket operation.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias fixes the category of the shared base.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @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 category.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IQuery describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export type IQuery = IBase<"query">;
+  /**
+   * A path parameter of a WebSocket operation with its field name.
+   *
+   * @evidence contracts/common.md#principled-implementation The record adds the field that names the path placeholder to the shared base.
+   * @evidence contracts/common.md#clear-and-simple-design A record extending the shared base.
+   * @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; its members are named for their meaning.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IReflectWebSocketOperationParameter.IParam describes protocol or type metadata; any embedded import/source record preserves the identity supplied by its owner. This declaration defines no native path conversion or process boundary.
+   */
   export interface IParam extends IBase<"param"> {
     field: string;
   }