@nestia/sdk 14.0.0 → 14.0.2

package/src/analyses/ReflectMcpOperationAnalyzer.ts

@@ -7,8 +7,28 @@ import { IReflectImport } from "../structures/IReflectImport";
 import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
 import { IReflectMcpOperationParameter } from "../structures/IReflectMcpOperationParameter";
 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;
@@ -17,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:
       | {
@@ -60,8 +90,8 @@ export namespace ReflectMcpOperationAnalyzer {
       );
 
     const imports: IReflectImport[] = [];
-    const parameters: IReflectMcpOperationParameter[] = preconfigured
-      .map((p) => {
+    const declared: IReflectMcpOperationParameter[] = preconfigured
+      .map((p): IReflectMcpOperationParameter | null => {
         const matched: IOperationMetadata.IParameter | undefined =
           ctx.metadata.parameters.find(
             (m: IOperationMetadata.IParameter) => p.index === m.index,
@@ -74,7 +104,7 @@ export namespace ReflectMcpOperationAnalyzer {
         }
         if (matched.type === null) {
           errors.push(
-            `Failed to analyze the parameter type of ${JSON.stringify(matched.name)}.`,
+            `Failed to analyze the parameter type of ${matched.name ? JSON.stringify(matched.name) : `the ${p.index} (th) argument`}.`,
           );
           return null;
         }
@@ -84,12 +114,16 @@ export namespace ReflectMcpOperationAnalyzer {
           name: matched.name,
           index: p.index,
           type: matched.type,
+          metadata: matched.primitive,
           imports: matched.imports,
           description: matched.description,
           jsDocTags: matched.jsDocTags,
         };
       })
       .filter((p): p is IReflectMcpOperationParameter => !!p);
+    // a destructured parameter declares no name, so it is given one
+    const parameters: IReflectMcpOperationParameter[] =
+      ParameterNameAnalyzer.name(declared);
 
     if (ctx.metadata.success?.imports?.length)
       imports.push(...ctx.metadata.success.imports);
@@ -116,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 => {

package/src/analyses/ReflectWebSocketOperationAnalyzer.ts

@@ -8,10 +8,30 @@ import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOpera
 import { IReflectWebSocketOperationParameter } from "../structures/IReflectWebSocketOperationParameter";
 import { StringUtil } from "../utils/StringUtil";
 import { ImportAnalyzer } from "./ImportAnalyzer";
+import { ParameterNameAnalyzer } from "./ParameterNameAnalyzer";
 import { PathAnalyzer } from "./PathAnalyzer";
 import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
 
+/**
+ * Reflects a `@WebSocketRoute` method into an operation.
+ *
+ * @evidence contracts/common.md#principled-implementation The parameter decorators give each parameter's category, the acceptor and driver type arguments are checked, the path parameters of the route are matched against the param decorators, and the tgrid declarations are not imported into the SDK.
+ * @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 ReflectWebSocketOperationAnalyzer 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 ReflectWebSocketOperationAnalyzer {
+  /**
+   * The input of the WebSocket 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 ReflectWebSocketOperationAnalyzer.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;
@@ -19,6 +39,16 @@ export namespace ReflectWebSocketOperationAnalyzer {
     name: string;
     metadata: IOperationMetadata;
   }
+  /**
+   * Returns the WebSocket operation of a method, or `null` when the method is
+   * not a WebSocket route or has errors.
+   *
+   * @evidence contracts/common.md#principled-implementation An acceptor is required, every parameter must carry one of the five decorators, the acceptor has three type arguments and the driver one, and the path parameters must equal the param fields.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @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 ReflectWebSocketOperationAnalyzer.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): IReflectWebSocketOperation | null => {
     const route: { paths: string[] } | undefined = Reflect.getMetadata(
       "nestia/WebSocketRoute",
@@ -51,7 +81,7 @@ export namespace ReflectWebSocketOperationAnalyzer {
       );
 
     const imports: IReflectImport[] = [];
-    const parameters: IReflectWebSocketOperationParameter[] = preconfigured
+    const declared: IReflectWebSocketOperationParameter[] = preconfigured
       .map((p) => {
         const reject = (message: string): null => {
           errors.push(message);
@@ -69,7 +99,7 @@ export namespace ReflectWebSocketOperationAnalyzer {
           );
         else if (matched.type === null)
           return reject(
-            `Failed to analyze the parameter type of the ${JSON.stringify(matched.name)}.`,
+            `Failed to analyze the parameter type of the ${matched.name ? JSON.stringify(matched.name) : `${p.index} th parameter`}.`,
           );
         else if (
           p.category === "param" &&
@@ -105,6 +135,7 @@ export namespace ReflectWebSocketOperationAnalyzer {
         if (
           p.category === "acceptor" ||
           p.category === "driver" ||
+          p.category === "header" ||
           p.category === "query"
         )
           return {
@@ -125,14 +156,16 @@ export namespace ReflectWebSocketOperationAnalyzer {
           } satisfies IReflectWebSocketOperationParameter.IParam;
         // UNKNOWN TYPE, MAYBE NEW FEATURE
         else {
-          if (p.category !== "header")
-            reject(
-              `@WebSocketRoute.${StringUtil.capitalize(p.category)}() has not been supported yet. How about upgrading the nestia packages?`,
-            );
+          reject(
+            `@WebSocketRoute.${StringUtil.capitalize(p.category)}() has not been supported yet. How about upgrading the nestia packages?`,
+          );
           return null;
         }
       })
       .filter((p): p is IReflectWebSocketOperationParameter => !!p);
+    // a destructured parameter declares no name, so it is given one
+    const parameters: IReflectWebSocketOperationParameter[] =
+      ParameterNameAnalyzer.name(declared);
 
     const fields: string[] = preconfigured
       .filter((p) => p.category === "param")
@@ -142,7 +175,7 @@ export namespace ReflectWebSocketOperationAnalyzer {
     for (const cLoc of ctx.controller.paths)
       for (const mLoc of route.paths) {
         const location: string = PathAnalyzer.join(cLoc, mLoc);
-        if (location.includes("*")) continue;
+        if (PathAnalyzer.wildcard(location)) continue;
 
         const binded: string[] | null = PathAnalyzer.parameters(location);
         if (binded === null)

package/src/analyses/SecurityAnalyzer.ts

@@ -1,25 +1,50 @@
-import { MapUtil } from "../utils/MapUtil";
-
+/**
+ * Helpers for security requirements.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace merges requirement lists into a canonical, duplicate-free list.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain helper.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SecurityAnalyzer 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 SecurityAnalyzer {
-  export const merge = (...entire: Record<string, string[]>[]) => {
-    const dict: Map<string | typeof none, Set<string>> = new Map();
-    for (const obj of entire) {
-      const entries = Object.entries(obj);
-      for (const [key, value] of entries) {
-        const set = MapUtil.take(dict, key, () => new Set());
-        for (const val of value) set.add(val);
-      }
-      if (entries.length === 0) MapUtil.take(dict, none, () => new Set());
-    }
+  /**
+   * Joins lists of security requirements into one, as OpenAPI reads them.
+   *
+   * Each requirement is an alternative, any one of which suffices, and every
+   * scheme of one requirement must hold, so each is kept as declared. Merging
+   * them by scheme name turned `{ a, b }` (both) into `a` or `b`, and the
+   * `read` or `write` scope alternatives of one scheme into both scopes. Only a
+   * requirement repeating an earlier one, such as a controller's restated on
+   * its method, is dropped; an empty one, anonymous access, is kept.
+   *
+   * @evidence contracts/common.md#principled-implementation Each requirement is normalized to unique scopes and keyed by its sorted schemes and sorted scopes, so equality does not depend on order, and the first occurrence keeps its position.
+   * @evidence contracts/common.md#clear-and-simple-design One function with one key computation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Equality is defined by content.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the equality and the order.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SecurityAnalyzer.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 = (
+    ...entire: Record<string, string[]>[]
+  ): Record<string, string[]>[] => {
     const output: Record<string, string[]>[] = [];
-    for (const [key, set] of dict)
-      key === none
-        ? output.push({})
-        : output.push({
-            [key]: [...set],
-          });
+    const visited: Set<string> = new Set();
+    for (const requirement of entire) {
+      const normalized: Record<string, string[]> = Object.fromEntries(
+        Object.entries(requirement).map(([name, scopes]) => [
+          name,
+          [...new Set(scopes)],
+        ]),
+      );
+      const key: string = JSON.stringify(
+        Object.entries(normalized)
+          .map(([name, scopes]) => [name, [...scopes].sort()] as const)
+          .sort(([x], [y]) => (x < y ? -1 : x > y ? 1 : 0)),
+      );
+      if (visited.has(key)) continue;
+      visited.add(key);
+      output.push(normalized);
+    }
     return output;
   };
-
-  const none = Symbol("none");
 }

package/src/analyses/SwaggerExampleAnalyzer.ts

@@ -0,0 +1,39 @@
+import { SwaggerExample } from "@nestia/core";
+import { OpenApi } from "@typia/interface";
+
+/**
+ * Converts the named examples of `@SwaggerExample` into OpenAPI example
+ * objects.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps each named value to an example object.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain mapping.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerExampleAnalyzer 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 SwaggerExampleAnalyzer {
+  /**
+   * The named examples `@SwaggerExample` attached, as the Example Objects an
+   * OpenAPI `examples` map holds.
+   *
+   * The decorator stores each named example as its value, and documents used to
+   * carry the value itself. OpenAPI 3.x names examples with Example Objects,
+   * whose `value` holds the value, so a tool read the raw value as an Example
+   * Object and found no example in it (#1649). `@TypedException()` examples are
+   * declared as Example Objects already.
+   *
+   * @evidence contracts/common.md#principled-implementation Each value is wrapped as `{ value }`, which is the OpenAPI example object.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional and one mapping.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The values are kept as given.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerExampleAnalyzer.examples 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 examples = (
+    data: SwaggerExample.IData<any> | undefined,
+  ): Record<string, OpenApi.IExample> | undefined =>
+    data?.examples === undefined
+      ? undefined
+      : Object.fromEntries(
+          Object.entries(data.examples).map(([key, value]) => [key, { value }]),
+        );
+}