@nestia/sdk 12.0.0-dev.20260601.1 → 12.0.0-dev.20260619.1

package/src/analyses/ImportAnalyzer.ts

@@ -1,92 +1,92 @@
-import { IReflectImport } from "../structures/IReflectImport";
-import { MapUtil } from "../utils/MapUtil";
-
-export namespace ImportAnalyzer {
-  /**
-   * @deprecated Removed in the Go-migration cycle. Import metadata is now
-   * attached by the native transformer in `packages/core/native/cmd/ttsc-nestia`
-   * and consumed via `IOperationMetadata.imports`. Call sites that previously
-   * walked a `ts.SourceFile` to derive imports should read the metadata
-   * delivered through `Reflect.getMetadata("nestia/OperationMetadata", …)`
-   * instead. See `packages/core/MIGRATION.md`.
-   */
-  export const analyze = (): never => {
-    throw new Error(
-      "ImportAnalyzer.analyze was removed in @nestia/sdk@next. " +
-        "Imports are now attached by the native transformer; read them from " +
-        "IOperationMetadata.imports (see packages/core/MIGRATION.md).",
-    );
-  };
-
-  export const merge = (imports: IReflectImport[]): IReflectImport[] => {
-    // group by files
-    const fileGroups: Map<string, IReflectImport[]> = new Map();
-    for (const imp of imports) {
-      const array: IReflectImport[] = MapUtil.take(
-        fileGroups,
-        imp.file,
-        () => [],
-      );
-      array.push(imp);
-    }
-    return Array.from(fileGroups.entries())
-      .map(([key, value]) => mergeGroup(key, value))
-      .flat();
-  };
-
-  function mergeGroup(
-    file: string,
-    imports: IReflectImport[],
-  ): IReflectImport[] {
-    const allStarImports: IReflectImport[] = Array.from(
-      new Set(
-        imports
-          .filter((imp) => imp.asterisk !== null)
-          .map((imp) => imp.asterisk!),
-      ),
-    )
-      .sort()
-      .map(
-        (allStarImport) =>
-          ({
-            file,
-            elements: [],
-            default: null,
-            asterisk: allStarImport,
-          }) satisfies IReflectImport,
-      );
-    const defaultImports: IReflectImport[] = Array.from(
-      new Set(
-        imports
-          .filter((imp) => imp.default !== null)
-          .map((imp) => imp.default!),
-      ),
-    )
-      .sort()
-      .map(
-        (defaultImport) =>
-          ({
-            file,
-            elements: [],
-            default: defaultImport,
-            asterisk: null,
-          }) satisfies IReflectImport,
-      );
-    const instances: Set<string> = new Set(
-      imports.map((imp) => imp.elements).flat(),
-    );
-    if (instances.size !== 0) {
-      if (defaultImports.length !== 0)
-        defaultImports[0]!.elements = Array.from(instances).sort();
-      else
-        defaultImports.push({
-          file,
-          elements: Array.from(instances).sort(),
-          default: null,
-          asterisk: null,
-        });
-    }
-    return [...allStarImports, ...defaultImports];
-  }
-
-}
+import { IReflectImport } from "../structures/IReflectImport";
+import { MapUtil } from "../utils/MapUtil";
+
+export namespace ImportAnalyzer {
+  /**
+   * @deprecated Removed in the Go-migration cycle. Import metadata is now
+   * attached by the native transformer in `packages/core/native/cmd/ttsc-nestia`
+   * and consumed via `IOperationMetadata.imports`. Call sites that previously
+   * walked a `ts.SourceFile` to derive imports should read the metadata
+   * delivered through `Reflect.getMetadata("nestia/OperationMetadata", …)`
+   * instead. See `packages/core/MIGRATION.md`.
+   */
+  export const analyze = (): never => {
+    throw new Error(
+      "ImportAnalyzer.analyze was removed in @nestia/sdk@next. " +
+        "Imports are now attached by the native transformer; read them from " +
+        "IOperationMetadata.imports (see packages/core/MIGRATION.md).",
+    );
+  };
+
+  export const merge = (imports: IReflectImport[]): IReflectImport[] => {
+    // group by files
+    const fileGroups: Map<string, IReflectImport[]> = new Map();
+    for (const imp of imports) {
+      const array: IReflectImport[] = MapUtil.take(
+        fileGroups,
+        imp.file,
+        () => [],
+      );
+      array.push(imp);
+    }
+    return Array.from(fileGroups.entries())
+      .map(([key, value]) => mergeGroup(key, value))
+      .flat();
+  };
+
+  function mergeGroup(
+    file: string,
+    imports: IReflectImport[],
+  ): IReflectImport[] {
+    const allStarImports: IReflectImport[] = Array.from(
+      new Set(
+        imports
+          .filter((imp) => imp.asterisk !== null)
+          .map((imp) => imp.asterisk!),
+      ),
+    )
+      .sort()
+      .map(
+        (allStarImport) =>
+          ({
+            file,
+            elements: [],
+            default: null,
+            asterisk: allStarImport,
+          }) satisfies IReflectImport,
+      );
+    const defaultImports: IReflectImport[] = Array.from(
+      new Set(
+        imports
+          .filter((imp) => imp.default !== null)
+          .map((imp) => imp.default!),
+      ),
+    )
+      .sort()
+      .map(
+        (defaultImport) =>
+          ({
+            file,
+            elements: [],
+            default: defaultImport,
+            asterisk: null,
+          }) satisfies IReflectImport,
+      );
+    const instances: Set<string> = new Set(
+      imports.map((imp) => imp.elements).flat(),
+    );
+    if (instances.size !== 0) {
+      if (defaultImports.length !== 0)
+        defaultImports[0]!.elements = Array.from(instances).sort();
+      else
+        defaultImports.push({
+          file,
+          elements: Array.from(instances).sort(),
+          default: null,
+          asterisk: null,
+        });
+    }
+    return [...allStarImports, ...defaultImports];
+  }
+
+}

package/src/analyses/PathAnalyzer.ts

@@ -1,69 +1,130 @@
-import path from "path";
-import { Token, parse } from "path-to-regexp";
-
-export namespace PathAnalyzer {
-  export const join = (...args: string[]) =>
-    "/" +
-    _Trim(
-      path
-        .join(...args.filter((s) => !!s.length))
-        .split("\\")
-        .join("/"),
-    );
-
-  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("/")
-    );
-  };
-
-  export const parameters = (str: string): string[] | null => {
-    const args = _Parse(str);
-    if (args === null) return null;
-    return args.filter((arg) => arg.type === "param").map((arg) => arg.value);
-  };
-
-  function _Parse(str: string): IArgument[] | null {
-    const tokens: Token[] | null = (() => {
-      try {
-        return parse(path.join(str).split("\\").join("/"));
-      } catch {
-        return null;
-      }
-    })();
-    if (tokens === null) return null;
-
-    const output: IArgument[] = [];
-    for (const key of tokens) {
-      if (typeof key === "string")
-        output.push({
-          type: "path",
-          value: _Trim(key),
-        });
-      else if (typeof key.name === "number" || _Trim(key.name) === "")
-        return null;
-      else
-        output.push({
-          type: "param",
-          value: _Trim(key.name),
-        });
-    }
-    return output;
-  }
-
-  function _Trim(str: string): string {
-    if (str[0] === "/") str = str.substring(1);
-    if (str[str.length - 1] === "/") str = str.substring(0, str.length - 1);
-    return str;
-  }
-
-  interface IArgument {
-    type: "param" | "path";
-    value: string;
-  }
-}
+import { RequestMethod } from "@nestjs/common";
+import path from "path";
+import { Token, parse } from "path-to-regexp";
+
+export namespace PathAnalyzer {
+  export const join = (...args: string[]) =>
+    "/" +
+    _Trim(
+      path
+        .join(...args.filter((s) => !!s.length))
+        .split("\\")
+        .join("/"),
+    );
+
+  export const joinWithGlobalPrefix = (props: {
+    globalPrefix: string;
+    exclude: IGlobalPrefixExclude[] | undefined;
+    excludePath?: string;
+    method: string;
+    path: string;
+  }): string =>
+    join(
+      isGlobalPrefixExcluded(
+        props.exclude,
+        props.excludePath ?? props.path,
+        props.method,
+      )
+        ? ""
+        : props.globalPrefix,
+      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("/")
+    );
+  };
+
+  export const parameters = (str: string): string[] | null => {
+    const args = _Parse(str);
+    if (args === null) return null;
+    return args.filter((arg) => arg.type === "param").map((arg) => arg.value);
+  };
+
+  function _Parse(str: string): IArgument[] | null {
+    const tokens: Token[] | null = (() => {
+      try {
+        return parse(path.join(str).split("\\").join("/"));
+      } catch {
+        return null;
+      }
+    })();
+    if (tokens === null) return null;
+
+    const output: IArgument[] = [];
+    for (const key of tokens) {
+      if (typeof key === "string")
+        output.push({
+          type: "path",
+          value: _Trim(key),
+        });
+      else if (typeof key.name === "number" || _Trim(key.name) === "")
+        return null;
+      else
+        output.push({
+          type: "param",
+          value: _Trim(key.name),
+        });
+    }
+    return output;
+  }
+
+  function _Trim(str: string): string {
+    if (str[0] === "/") str = str.substring(1);
+    if (str[str.length - 1] === "/") str = str.substring(0, str.length - 1);
+    return str;
+  }
+
+  function isGlobalPrefixExcluded(
+    exclude: IGlobalPrefixExclude[] | undefined,
+    path: string,
+    method: string,
+  ): boolean {
+    if (exclude === undefined) return false;
+    const requestMethod: RequestMethod | undefined = REQUEST_METHODS[method];
+    if (requestMethod === undefined) return false;
+
+    const location: string = join(path);
+    return exclude.some((route) => {
+      const routeMethod: RequestMethod | undefined =
+        route.requestMethod ?? route.method;
+      if (
+        routeMethod !== undefined &&
+        routeMethod !== RequestMethod.ALL &&
+        routeMethod !== requestMethod
+      )
+        return false;
+      if (route.pathRegex instanceof RegExp)
+        return route.pathRegex.test(join(location));
+      return join(route.path) === location;
+    });
+  }
+
+  interface IArgument {
+    type: "param" | "path";
+    value: string;
+  }
+
+  interface IGlobalPrefixExclude {
+    path: string;
+    method?: RequestMethod;
+    requestMethod?: RequestMethod;
+    pathRegex?: RegExp;
+  }
+}
+
+const REQUEST_METHODS: Record<string, RequestMethod> = {
+  DELETE: RequestMethod.DELETE,
+  GET: RequestMethod.GET,
+  HEAD: RequestMethod.HEAD,
+  OPTIONS: RequestMethod.OPTIONS,
+  PATCH: RequestMethod.PATCH,
+  POST: RequestMethod.POST,
+  PUT: RequestMethod.PUT,
+};

package/src/analyses/ReflectControllerAnalyzer.ts

@@ -1,105 +1,112 @@
-import {
-  HOST_METADATA,
-  PATH_METADATA,
-  SCOPE_OPTIONS_METADATA,
-} from "@nestjs/common/constants";
-
-import { INestiaProject } from "../structures/INestiaProject";
-import { INestiaSdkInput } from "../structures/INestiaSdkInput";
-import { IReflectController } from "../structures/IReflectController";
-import { IReflectHttpOperation } from "../structures/IReflectHttpOperation";
-import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
-import { IOperationMetadata } from "../structures/IOperationMetadata";
-import { ArrayUtil } from "../utils/ArrayUtil";
-import { ReflectHttpOperationAnalyzer } from "./ReflectHttpOperationAnalyzer";
-import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
-import { ReflectWebSocketOperationAnalyzer } from "./ReflectWebSocketOperationAnalyzer";
-
-export namespace ReflectControllerAnalyzer {
-  export interface IProps {
-    project: Omit<INestiaProject, "config">;
-    controller: INestiaSdkInput.IController;
-    unique: WeakSet<Function>;
-  }
-  /* ---------------------------------------------------------
-    CONTROLLER
-  --------------------------------------------------------- */
-  export const analyze = (props: IProps): IReflectController | null => {
-    // MUST BE TYPE OF A CREATOR WHO HAS THE CONSTRUCTOR
-    if (
-      ArrayUtil.has(
-        Reflect.getMetadataKeys(props.controller.class),
-        PATH_METADATA,
-        HOST_METADATA,
-        SCOPE_OPTIONS_METADATA,
-      ) === false
-    )
-      return null;
-
-    // BASIC INFO
-    const controller: IReflectController = {
-      class: props.controller.class,
-      file: props.controller.location,
-      operations: [],
-      prefixes: props.controller.prefixes,
-      paths: ReflectMetadataAnalyzer.paths(props.controller.class).filter(
-        (str) => {
-          if (str.includes("*") === true) {
-            props.project.warnings.push({
-              file: props.controller.location,
-              class: props.controller.class.name,
-              function: null,
-              from: null,
-              contents: ["@nestia/sdk does not compose wildcard controller."],
-            });
-            return false;
-          }
-          return true;
-        },
-      ),
-      versions: ReflectMetadataAnalyzer.versions(props.controller.class),
-      security: ReflectMetadataAnalyzer.securities(props.controller.class),
-      tags:
-        Reflect.getMetadata("swagger/apiUseTags", props.controller.class) ?? [],
-    };
-
-    // OPERATORS
-    for (const [key, value] of _Get_prototype_entries(props.controller.class)) {
-      if (typeof value !== "function") continue;
-      const metadata: IOperationMetadata | undefined = Reflect.getMetadata(
-        "nestia/OperationMetadata",
-        props.controller.class.prototype,
-        key,
-      );
-      if (metadata === undefined) continue;
-      else if (metadata.jsDocTags.some((tag) => tag.name === "ignore"))
-        continue;
-      const next: ReflectHttpOperationAnalyzer.IProps = {
-        project: props.project,
-        controller: controller,
-        name: key,
-        function: value,
-        metadata,
-      };
-      const child: IReflectHttpOperation | IReflectWebSocketOperation | null =
-        ReflectWebSocketOperationAnalyzer.analyze(next) ??
-        ReflectHttpOperationAnalyzer.analyze(next);
-      if (child !== null) controller.operations.push(child);
-    }
-    return controller;
-  };
-
-  function _Get_prototype_entries(creator: any): Array<[string, unknown]> {
-    const keyList = Object.getOwnPropertyNames(creator.prototype);
-    const entries: Array<[string, unknown]> = keyList.map((key) => [
-      key,
-      creator.prototype[key],
-    ]);
-
-    const parent = Object.getPrototypeOf(creator);
-    if (parent.prototype !== undefined)
-      entries.push(..._Get_prototype_entries(parent));
-
-    return entries;
-  }
-}
+import {
+  HOST_METADATA,
+  PATH_METADATA,
+  SCOPE_OPTIONS_METADATA,
+} from "@nestjs/common/constants";
+
+import { INestiaProject } from "../structures/INestiaProject";
+import { INestiaSdkInput } from "../structures/INestiaSdkInput";
+import { IReflectController } from "../structures/IReflectController";
+import { IReflectHttpOperation } from "../structures/IReflectHttpOperation";
+import { IReflectMcpOperation } from "../structures/IReflectMcpOperation";
+import { IReflectWebSocketOperation } from "../structures/IReflectWebSocketOperation";
+import { IOperationMetadata } from "../structures/IOperationMetadata";
+import { ArrayUtil } from "../utils/ArrayUtil";
+import { ReflectHttpOperationAnalyzer } from "./ReflectHttpOperationAnalyzer";
+import { ReflectMcpOperationAnalyzer } from "./ReflectMcpOperationAnalyzer";
+import { ReflectMetadataAnalyzer } from "./ReflectMetadataAnalyzer";
+import { ReflectWebSocketOperationAnalyzer } from "./ReflectWebSocketOperationAnalyzer";
+
+export namespace ReflectControllerAnalyzer {
+  export interface IProps {
+    project: Omit<INestiaProject, "config">;
+    controller: INestiaSdkInput.IController;
+    unique: WeakSet<Function>;
+  }
+  /* ---------------------------------------------------------
+    CONTROLLER
+  --------------------------------------------------------- */
+  export const analyze = (props: IProps): IReflectController | null => {
+    // MUST BE TYPE OF A CREATOR WHO HAS THE CONSTRUCTOR
+    if (
+      ArrayUtil.has(
+        Reflect.getMetadataKeys(props.controller.class),
+        PATH_METADATA,
+        HOST_METADATA,
+        SCOPE_OPTIONS_METADATA,
+      ) === false
+    )
+      return null;
+
+    // BASIC INFO
+    const controller: IReflectController = {
+      class: props.controller.class,
+      file: props.controller.location,
+      operations: [],
+      prefixes: props.controller.prefixes,
+      paths: ReflectMetadataAnalyzer.paths(props.controller.class).filter(
+        (str) => {
+          if (str.includes("*") === true) {
+            props.project.warnings.push({
+              file: props.controller.location,
+              class: props.controller.class.name,
+              function: null,
+              from: null,
+              contents: ["@nestia/sdk does not compose wildcard controller."],
+            });
+            return false;
+          }
+          return true;
+        },
+      ),
+      versions: ReflectMetadataAnalyzer.versions(props.controller.class),
+      security: ReflectMetadataAnalyzer.securities(props.controller.class),
+      tags:
+        Reflect.getMetadata("swagger/apiUseTags", props.controller.class) ?? [],
+    };
+
+    // OPERATORS
+    for (const [key, value] of _Get_prototype_entries(props.controller.class)) {
+      if (typeof value !== "function") continue;
+      const metadata: IOperationMetadata | undefined = Reflect.getMetadata(
+        "nestia/OperationMetadata",
+        props.controller.class.prototype,
+        key,
+      );
+      if (metadata === undefined) continue;
+      else if (metadata.jsDocTags.some((tag) => tag.name === "ignore"))
+        continue;
+      const next: ReflectHttpOperationAnalyzer.IProps = {
+        project: props.project,
+        controller: controller,
+        name: key,
+        function: value,
+        metadata,
+      };
+      const child:
+        | IReflectHttpOperation
+        | IReflectWebSocketOperation
+        | IReflectMcpOperation
+        | null =
+        ReflectMcpOperationAnalyzer.analyze(next) ??
+        ReflectWebSocketOperationAnalyzer.analyze(next) ??
+        ReflectHttpOperationAnalyzer.analyze(next);
+      if (child !== null) controller.operations.push(child);
+    }
+    return controller;
+  };
+
+  function _Get_prototype_entries(creator: any): Array<[string, unknown]> {
+    const keyList = Object.getOwnPropertyNames(creator.prototype);
+    const entries: Array<[string, unknown]> = keyList.map((key) => [
+      key,
+      creator.prototype[key],
+    ]);
+
+    const parent = Object.getPrototypeOf(creator);
+    if (parent.prototype !== undefined)
+      entries.push(..._Get_prototype_entries(parent));
+
+    return entries;
+  }
+}