@nestia/sdk 14.0.1 → 14.0.2

package/src/analyses/ReflectWebSocketOperationAnalyzer.ts

@@ -12,7 +12,26 @@ 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;
@@ -20,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",
@@ -106,6 +135,7 @@ export namespace ReflectWebSocketOperationAnalyzer {
         if (
           p.category === "acceptor" ||
           p.category === "driver" ||
+          p.category === "header" ||
           p.category === "query"
         )
           return {
@@ -126,10 +156,9 @@ 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;
         }
       })

package/src/analyses/SecurityAnalyzer.ts

@@ -1,3 +1,12 @@
+/**
+ * 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 {
   /**
    * Joins lists of security requirements into one, as OpenAPI reads them.
@@ -8,6 +17,12 @@ export namespace SecurityAnalyzer {
    * `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[]>[]

package/src/analyses/SwaggerExampleAnalyzer.ts

@@ -1,6 +1,16 @@
 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
@@ -11,6 +21,12 @@ export namespace SwaggerExampleAnalyzer {
    * 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,