@nestia/sdk 14.0.0 → 14.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "14.0.0",
+  "version": "14.0.2",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "bin": {
@@ -55,12 +55,13 @@
     "tgrid": "^1.2.1",
     "ttsc": "^0.28.1",
     "tstl": "^3.0.0",
-    "typia": "^15.0.0",
-    "@nestia/fetcher": "^14.0.0",
-    "@nestia/core": "^14.0.0"
+    "typia": "15.0.0",
+    "@babel/parser": "^7.29.8",
+    "@nestia/core": "^14.0.2",
+    "@nestia/fetcher": "^14.0.2"
   },
   "peerDependencies": {
-    "@nestia/core": "^14.0.0"
+    "@nestia/core": "^14.0.2"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.18.0",
@@ -88,7 +89,8 @@
   "scripts": {
     "build": "rimraf lib && ttsc",
     "dev": "ttsc --watch",
-    "test:go": "cd test && go test ./..."
+    "test:go": "cd test && go test -count=1 ./...",
+    "evidence": "evidence"
   },
   "types": "lib/index.d.ts"
 }

package/src/INestiaConfig.ts

@@ -5,6 +5,11 @@ import type { OpenApi } from "typia";
  * Definition for the `nestia.config.ts` file.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation The input names the controllers to analyze and every optional property enables or refines one output (SDK, distribution, e2e, Swagger), so one configuration file drives every generator.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record whose nested types describe the input and the Swagger options.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation Every property documents its meaning and default, which are the public contract of the configuration file.
+ * @evidence contracts/portability.md#os-neutral-implementation Source inputs and output/distribution/e2e destinations carry native pathname strings interpreted by their owning Node filesystem operations; the application callback bypasses source compilation. Swagger route paths are distinct protocol values, not native file identities.
  */
 export interface INestiaConfig {
   /**
@@ -49,11 +54,16 @@ export interface INestiaConfig {
    */
   distribute?: string;
 
-  /** @default false */
+  /**
+   * Groups HTTP and WebSocket SDK call arguments in one props object after the
+   * connection. MCP wrappers retain their client and arguments parameters.
+   *
+   * @default false
+   */
   keyword?: boolean;
 
   /**
-   * Allow simulation mode.
+   * Allow simulation mode for HTTP SDK calls.
    *
    * If you configure this property to be `true`, the SDK library would be
    * contain simulation mode. In the simulation mode, the SDK library would not
@@ -72,7 +82,8 @@ export interface INestiaConfig {
    *
    * If you configure this property and runs `npx nestia e2e` command,
    * `@nestia/sdk` will analyze your NestJS backend server code, and generates
-   * e2e test functions for every API endpoints.
+   * e2e test functions for the analyzed HTTP endpoints. WebSocket and MCP
+   * operations have no generated HTTP test function.
    *
    * If not configured, you can't run `npx nestia e2e` command.
    */
@@ -82,10 +93,10 @@ export interface INestiaConfig {
    * Whether to use propagation mode or not.
    *
    * If being configured, interaction functions of the SDK library would perform
-   * the propagation mode. The propagation mode means that never throwing
-   * exception even when status code is not 200 (or 201), but just returning the
+   * propagation mode. HTTP failure statuses are returned through the
    * {@link IPropagation} typed instance, which can specify its body type through
-   * discriminated union determined by status code.
+   * discriminated union determined by status code. Transport, decoding and
+   * configured assertion failures can still throw.
    *
    * @default false
    */
@@ -94,9 +105,10 @@ export interface INestiaConfig {
   /**
    * Whether to clone DTO structures or not.
    *
-   * If being configured, all of DTOs used in the backend server would be cloned
-   * into the `structures` directory, and the SDK library would be refer to the
-   * cloned DTOs instead of the original.
+   * If enabled, named DTOs reachable from analyzed routes are emitted into
+   * `structures`, with anonymous forms written inline. HTTP and MCP DTOs use
+   * their wire metadata; supported WebSocket declarations are copied from local
+   * sources, while external or unsupported imports retain source links.
    *
    * @default false
    */
@@ -105,8 +117,10 @@ export interface INestiaConfig {
   /**
    * Whether to wrap DTO by primitive type.
    *
-   * If you don't configure this property as `false`, all of DTOs in the SDK
-   * library would be automatically wrapped by {@link Primitive} type.
+   * Unless false, source DTO aliases use Primitive for JSON bodies and
+   * responses, and Resolved for query, headers and other resolved wire forms.
+   * Clone mode writes the analyzed metadata directly; multipart bodies use
+   * FormDataInput and binary responses use ReadableStream.
    *
    * For refenrece, if a DTO type be capsuled by the {@link Primitive} type, all
    * of methods in the DTO type would be automatically erased. Also, if the DTO
@@ -120,9 +134,10 @@ export interface INestiaConfig {
   /**
    * Whether to assert parameter types or not.
    *
-   * If you configure this property to be `true`, all of the function parameters
-   * of SDK library would be checked through [`typia.assert<T>()`
-   * function](https://typia.io/docs/validators/assert/).
+   * If true, HTTP path, query and body arguments are checked through
+   * [`typia.assert<T>()` function](https://typia.io/docs/validators/assert/).
+   * The connection, connection headers, WebSocket and MCP arguments are outside
+   * this option.
    *
    * This option would make your SDK library compilation time a little bit
    * slower, but would enahcne the type safety even in the runtime level.
@@ -132,16 +147,13 @@ export interface INestiaConfig {
   assert?: boolean;
 
   /**
-   * Whether to optimize JSON string conversion 10x faster or not.
-   *
-   * If you configure this property to be `true`, the SDK library would utilize
-   * the [`typia.assertStringify<T>()
-   * function`](https://github.com/samchon/typia#enhanced-json) to boost up JSON
-   * serialization speed and ensure type safety.
+   * Generates specialized JSON serialization for JSON and encrypted request
+   * bodies.
    *
-   * This option would make your SDK library compilation time a little bit
-   * slower, but would enhance JSON serialization speed 10x faster. Also, it can
-   * ensure type safety even in the runtime level.
+   * When enabled, the SDK emits a `typia.json.assertStringify` function for the
+   * body type. With `assert` enabled, argument validation runs separately and
+   * serialization uses `typia.json.stringify` without repeating the assertion.
+   * Compilation and runtime costs depend on the body type and workload.
    *
    * @default false
    */
@@ -151,6 +163,12 @@ export namespace INestiaConfig {
   /**
    * List of files or directories to include or exclude to specifying the NestJS
    * controllers.
+   *
+   * @evidence contracts/common.md#principled-implementation Include lists select controller files or directories and exclude lists remove files from that selection.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record.
+   * @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.
+   * @evidence contracts/portability.md#os-neutral-implementation Include and exclude strings represent native files, directories or glob patterns. SourceFinder owns resolving them against the current working directory and distinguishing literal existing paths from wildcard suffixes.
    */
   export interface IInput {
     /** List of files or directories containing the NestJS controller classes. */
@@ -160,7 +178,15 @@ export namespace INestiaConfig {
     exclude?: string[];
   }
 
-  /** Building `swagger.json` is also possible. */
+  /**
+   * Building `swagger.json` is also possible.
+   *
+   * @evidence contracts/common.md#principled-implementation The output path is required and every other option refines the composed OpenAPI document before it is written.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record of options with one callback.
+   * @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.
+   * @evidence contracts/portability.md#os-neutral-implementation output is a native destination interpreted by path.parse/resolve in SwaggerGenerator; a nonempty extension denotes a file and otherwise the destination is a directory. Server URLs and operation paths retain protocol spelling independently of that filesystem boundary.
+   */
   export interface ISwaggerConfig {
     /**
      * Response path of the `swagger.json`.
@@ -174,12 +200,11 @@ export namespace INestiaConfig {
     /**
      * OpenAPI version.
      *
-     * If you configure this property to be `2.0` or `3.0`, the newly generated
-     * `swagger.json` file would follow the specified OpenAPI version. The newly
-     * generated `swagger.json` file would be downgraded from the OpenAPI v3.1
-     * specification by {@link OpenApi.downgrade} method.
+     * If you configure this property to be `2.0`, `3.0`, or `3.1`, the newly
+     * generated `swagger.json` file would follow the specified OpenAPI version,
+     * downgraded from the OpenAPI v3.2 specification.
      *
-     * @default 3.1
+     * @default 3.2
      */
     openapi?: "2.0" | "3.0" | "3.1" | "3.2";
 
@@ -199,10 +224,12 @@ export namespace INestiaConfig {
      * Whether to include additional information or not.
      *
      * If configured to be `true`, those properties would be added into each API
-     * endpoinnt.
+     * endpoint.
      *
-     * - `x-nestia-method`
-     * - `x-nestia-namespace` ` `x-nestia-jsDocTags`
+     * - `x-nestia-method`: the HTTP method, such as `"GET"`
+     * - `x-nestia-namespace`: the SDK function's accessor, such as
+     *   `"bbs.articles.index"`
+     * - `x-nestia-jsDocTags`: the JSDoc tags of the controller method
      *
      * @default false
      */
@@ -223,7 +250,10 @@ export namespace INestiaConfig {
      *
      * When generating `swagger.json` file through `nestia`, if your controllers
      * or theirs methods have a security key which is not enrolled in here
-     * property, it would be an error.
+     * property, it would be an error. So would an OAuth2 scope none of the
+     * scheme's flows declares, and, for an OpenAPI `3.0` or `2.0` document,
+     * scopes on a scheme other than OAuth2 or OpenID Connect, which those
+     * versions require to be empty; from `3.1` on they list role names.
      */
     security?: Record<string, OpenApi.ISecurityScheme>;
 
@@ -245,7 +275,12 @@ export namespace INestiaConfig {
      * If you configure this property to be `true`, the query DTO would be
      * decomposed into individual query parameters per each property. Otherwise
      * you set it to be `false`, the query DTO would be one object type which
-     * contains all of query parameters.
+     * contains all of query parameters, spread into its keys by `style: form`
+     * and `explode: true`.
+     *
+     * Swagger 2.0 has no object query parameter, and no OpenAPI version can
+     * spread an object into headers, so a query DTO of a Swagger 2.0 document
+     * and a headers DTO are decomposed regardless of this property.
      *
      * @default true
      */
@@ -256,6 +291,11 @@ export namespace INestiaConfig {
      *
      * @param props Properties of the API endpoint.
      * @returns Operation ID.
+     * @evidence contracts/common.md#principled-implementation An explicit @operationId tag takes precedence; otherwise this callback receives the four identifying facts once for the composed operation and supplies its identifier.
+     * @evidence contracts/common.md#clear-and-simple-design One optional callback with a single argument object.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a caller-supplied function and nothing about a particular naming scheme is built in.
+     * @evidence contracts/common.md#meaningful-documentation The comment documents the arguments and the result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation This callback receives HTTP endpoint identity and returns an OpenAPI identifier; it owns no native pathname or process boundary.
      */
     operationId?(props: {
       class: string;

package/src/NestiaSdkApplication.ts

@@ -25,9 +25,34 @@ import { ITypedWebSocketRoute } from "./structures/ITypedWebSocketRoute";
 import { StringUtil } from "./utils/StringUtil";
 import { VersioningStrategy } from "./utils/VersioningStrategy";
 
+/**
+ * Runs the generators of `@nestia/sdk` over one configuration.
+ *
+ * Each method validates the configuration for the output it needs, analyzes the
+ * controllers and the TypeScript metadata, reports every error at once, and
+ * then generates.
+ *
+ * @evidence contracts/common.md#principled-implementation The shared pipeline reflects controllers, types routes from transform metadata, assigns accessors and rejects collected analysis errors before writing. SDK-specific representability checks are attached by sdk and SDK-producing all; e2e currently invokes the SDK writer without that additional validation callback.
+ * @evidence contracts/common.md#clear-and-simple-design One class with four public generators over one private pipeline; directory assertion, title, and error report are module-private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No controller or route name is special-cased; the same pipeline serves the CLI and programmatic callers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the four generators and that the errors of an analysis are reported together.
+ * @evidence contracts/portability.md#os-neutral-implementation Output checks and diagnostic locations use Node fs.stat and path operations; controller compilation and output writes remain owned by ConfigAnalyzer and the generators. Filesystem errors distinguish missing/non-directory locations from other native failures.
+ */
 export class NestiaSdkApplication {
   public constructor(private readonly config: INestiaConfig) {}
 
+  /**
+   * Generates everything the configuration asks for: the SDK and its e2e tests
+   * when `output` is set, and the Swagger document when `swagger` is set.
+   *
+   * It throws when neither `output` nor `swagger.output` is configured.
+   *
+   * @evidence contracts/common.md#principled-implementation The SDK validation is attached only when an SDK is generated, so a Swagger-only run does not fail on SDK rules, and the e2e tests are generated after the SDK they import.
+   * @evidence contracts/common.md#clear-and-simple-design One method that composes the generators inside the shared pipeline.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The error names the properties a caller can configure; none is stale.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is generated and the failure.
+   * @evidence contracts/portability.md#os-neutral-implementation all delegates configured output creation to the native writers and does not apply the explicit parent-directory checks used by sdk/e2e/swagger. Diagnostic source paths are rendered relative to the current native working directory.
+   */
   public async all(): Promise<void> {
     if (!this.config.output && !this.config.swagger?.output)
       throw new Error(
@@ -36,7 +61,6 @@ export class NestiaSdkApplication {
           "",
           "  - INestiaConfig.output",
           "  - INestiaConfig.swagger.output",
-          "  - INestiaConfig.openai.output",
         ].join("\n"),
       );
     print_title("Nestia All Generator");
@@ -52,6 +76,18 @@ export class NestiaSdkApplication {
     });
   }
 
+  /**
+   * Generates the SDK and the automatic e2e test functions.
+   *
+   * It throws when `output` or `e2e` is missing, or when the parent directory
+   * of either does not exist.
+   *
+   * @evidence contracts/common.md#principled-implementation The e2e functions import the generated SDK, so the SDK is generated first, and both parent directories are asserted before any analysis runs.
+   * @evidence contracts/common.md#clear-and-simple-design One method over the shared pipeline.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The directory check follows the configuration and no path is special-cased.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the requirements and the failures.
+   * @evidence contracts/portability.md#os-neutral-implementation path.resolve obtains each native parent and fs.stat follows symlinks to verify a directory before analysis. ENOENT/ENOTDIR become configuration diagnostics; permission and other filesystem errors propagate without a platform-specific shell fallback.
+   */
   public async e2e(): Promise<void> {
     if (!this.config.output)
       throw new Error(
@@ -62,18 +98,18 @@ export class NestiaSdkApplication {
         "Error on NestiaApplication.e2e(): configure INestiaConfig.e2e property.",
       );
 
-    const validate =
-      (title: string) =>
-      async (location: string): Promise<void> => {
-        const parent: string = path.resolve(location + "/..");
-        const stats: fs.Stats = await fs.promises.lstat(parent);
-        if (stats.isDirectory() === false)
-          throw new Error(
-            `Error on NestiaApplication.e2e(): output directory of ${title} does not exists.`,
-          );
-      };
-    await validate("sdk")(this.config.output);
-    await validate("e2e")(this.config.e2e);
+    await assertDirectory({
+      method: "e2e",
+      property: "output",
+      location: this.config.output,
+      directory: path.resolve(this.config.output + "/.."),
+    });
+    await assertDirectory({
+      method: "e2e",
+      property: "e2e",
+      location: this.config.e2e,
+      directory: path.resolve(this.config.e2e + "/.."),
+    });
 
     print_title("Nestia E2E Generator");
     await this.generate({
@@ -84,18 +120,29 @@ export class NestiaSdkApplication {
     });
   }
 
+  /**
+   * Generates the SDK library.
+   *
+   * It throws when `output` is missing or its parent directory does not exist.
+   *
+   * @evidence contracts/common.md#principled-implementation The SDK validation runs after route typing and before the generator, so a route the SDK cannot express is reported instead of written.
+   * @evidence contracts/common.md#clear-and-simple-design One method over the shared pipeline.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The directory check follows the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the requirement and the failures.
+   * @evidence contracts/portability.md#os-neutral-implementation The configured output parent is resolved through Node path and verified by fs.stat, including linked directories. Generator writes use their own native boundaries; this entry does not infer case identity from an OS name.
+   */
   public async sdk(): Promise<void> {
     if (!this.config.output)
       throw new Error(
         "Error on NestiaApplication.sdk(): configure INestiaConfig.output property.",
       );
 
-    const parent: string = path.resolve(this.config.output + "/..");
-    const stats: fs.Stats = await fs.promises.lstat(parent);
-    if (stats.isDirectory() === false)
-      throw new Error(
-        "Error on NestiaApplication.sdk(): output directory does not exists.",
-      );
+    await assertDirectory({
+      method: "sdk",
+      property: "output",
+      location: this.config.output,
+      directory: path.resolve(this.config.output + "/.."),
+    });
 
     print_title("Nestia SDK Generator");
     await this.generate({
@@ -104,6 +151,18 @@ export class NestiaSdkApplication {
     });
   }
 
+  /**
+   * Generates the Swagger document.
+   *
+   * It throws when `swagger.output` is missing or the directory that will hold
+   * the document does not exist; the output may be a file or a directory.
+   *
+   * @evidence contracts/common.md#principled-implementation The directory to check is the parent of a file path with an extension and the path itself otherwise, which is how the generator decides where to write.
+   * @evidence contracts/common.md#clear-and-simple-design One method over the shared pipeline.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the generator's own output rule.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the requirement and the two output forms.
+   * @evidence contracts/portability.md#os-neutral-implementation path.parse/resolve decide the native containing directory from whether the output has an extension, matching SwaggerGenerator's destination rule. The common directory check distinguishes missing paths from non-directory entries and propagates other filesystem errors.
+   */
   public async swagger(): Promise<void> {
     if (!this.config.swagger?.output)
       throw new Error(
@@ -111,14 +170,14 @@ export class NestiaSdkApplication {
       );
 
     const parsed: path.ParsedPath = path.parse(this.config.swagger.output);
-    const directory: string = !!parsed.ext
-      ? path.resolve(parsed.dir)
-      : this.config.swagger.output;
-    const stats: fs.Stats = await fs.promises.lstat(directory);
-    if (stats.isDirectory() === false)
-      throw new Error(
-        "Error on NestiaApplication.swagger(): output directory does not exists.",
-      );
+    await assertDirectory({
+      method: "swagger",
+      property: "swagger.output",
+      location: this.config.swagger.output,
+      directory: !!parsed.ext
+        ? path.resolve(parsed.dir)
+        : path.resolve(this.config.swagger.output),
+    });
 
     print_title("Nestia Swagger Generator");
     await this.generate({
@@ -198,10 +257,6 @@ export class NestiaSdkApplication {
     //----
     console.log("Analyzing source codes");
 
-    // METADATA COMPONENTS
-    const sourceCollection: IMetadataDictionary =
-      TypedHttpRouteAnalyzer.dictionary(controllers);
-
     // CONVERT TO TYPED OPERATIONS
     const routes: Array<
       ITypedHttpRoute | ITypedWebSocketRoute | ITypedMcpRoute
@@ -213,15 +268,17 @@ export class NestiaSdkApplication {
             ...TypedMcpRouteAnalyzer.analyze({
               controller: c,
               operation: o,
+              clone: project.config.clone,
+              errors: project.errors,
             }),
           );
           continue;
         }
         const pathList: Set<string> = new Set();
-        const versions: string[] = VersioningStrategy.merge(project)([
-          ...(c.versions ?? []),
-          ...(o.versions ?? []),
-        ]);
+        const versions: string[] = VersioningStrategy.merge(project)({
+          controller: c.versions,
+          method: o.versions,
+        });
         for (const v of versions)
           for (const prefix of wrapPaths(c.prefixes))
             for (const cPath of wrapPaths(c.paths))
@@ -246,7 +303,6 @@ export class NestiaSdkApplication {
             ...TypedHttpRouteAnalyzer.analyze({
               controller: c,
               errors: project.errors,
-              dictionary: sourceCollection,
               operation: o,
               paths: Array.from(pathList),
             }),
@@ -264,7 +320,10 @@ export class NestiaSdkApplication {
 
     const collection: IMetadataDictionary =
       TypedHttpRouteAnalyzer.routeDictionary(
-        routes.filter((r): r is ITypedHttpRoute => r.protocol === "http"),
+        routes.filter(
+          (r): r is ITypedHttpRoute | ITypedMcpRoute =>
+            r.protocol !== "websocket",
+        ),
       );
 
     if (props.validate !== undefined)
@@ -288,6 +347,30 @@ export class NestiaSdkApplication {
   }
 }
 
+/**
+ * Asserts the directory an output is written into exists, naming the configured
+ * location. `fs.promises.stat()` itself rejects a missing path, so it is caught
+ * rather than left to surface as a bare `ENOENT`; a symbolic link to a
+ * directory is followed.
+ */
+const assertDirectory = async (props: {
+  method: string;
+  property: string;
+  location: string;
+  directory: string;
+}): Promise<void> => {
+  const stats: fs.Stats | null = await fs.promises
+    .stat(props.directory)
+    .catch((error: NodeJS.ErrnoException): null => {
+      if (error.code === "ENOENT" || error.code === "ENOTDIR") return null;
+      throw error;
+    });
+  if (stats === null || stats.isDirectory() === false)
+    throw new Error(
+      `Error on NestiaApplication.${props.method}(): directory ${JSON.stringify(props.directory)} of INestiaConfig.${props.property} ${JSON.stringify(props.location)} ${stats === null ? "does not exist" : "is not a directory"}.`,
+    );
+};
+
 const print_title = (str: string): void => {
   console.log("-----------------------------------------------------------");
   console.log(` ${str}`);
@@ -308,6 +391,8 @@ const report = (props: {
   console.log("");
   print_title(`Nestia ${StringUtil.capitalize(props.type)} Report`);
 
+  // every contradiction at once, not only the first function's
+  const messages: string[] = [];
   for (const {
     first: { error },
     second: contents,
@@ -318,24 +403,27 @@ const report = (props: {
       `${location} - `,
       error.class,
       ...(error.function !== null ? [`.${error.function}()`] : [""]),
-      ...(error.from !== null ? [` from ${error.from}`] : [""]),
+      // an empty origin names no part of the function
+      ...(error.from ? [` from ${error.from}`] : [""]),
       ":\n",
       contents
         .map((c) => {
           if (typeof c === "string") return `  - ${c}`;
           else
             return [
+              // the property the type was found at, when there is one
               c.accessor
-                ? `  - ${c.name}: `
-                : `  - ${c.name} (${c.accessor}): `,
+                ? `  - ${c.name} (${c.accessor}): `
+                : `  - ${c.name}: `,
               ...c.messages.map((msg) => `    - ${msg}`),
             ].join("\n");
         })
         .join("\n"),
     ].join("");
-    if (props.type === "error") throw new Error(message);
+    if (props.type === "error") messages.push(message);
     else console.log(message);
   }
+  if (messages.length !== 0) throw new Error(messages.join("\n\n"));
 };
 
 const wrapPaths = (paths: string[]): string[] =>

package/src/NestiaSwaggerComposer.ts

@@ -12,7 +12,6 @@ import { PathAnalyzer } from "./analyses/PathAnalyzer";
 import { ReflectControllerAnalyzer } from "./analyses/ReflectControllerAnalyzer";
 import { TypedHttpRouteAnalyzer } from "./analyses/TypedHttpRouteAnalyzer";
 import { SwaggerGenerator } from "./generates/SwaggerGenerator";
-import { IMetadataDictionary } from "./internal/legacy";
 import { INestiaProject } from "./structures/INestiaProject";
 import { INestiaSdkInput } from "./structures/INestiaSdkInput";
 import { IOperationMetadata } from "./structures/IOperationMetadata";
@@ -21,7 +20,28 @@ import { IReflectOperationError } from "./structures/IReflectOperationError";
 import { ITypedHttpRoute } from "./structures/ITypedHttpRoute";
 import { VersioningStrategy } from "./utils/VersioningStrategy";
 
+/**
+ * Composes the Swagger document of a running NestJS application, without files.
+ *
+ * @evidence contracts/common.md#principled-implementation The controllers are taken from the application's module graph and analyzed like the CLI does, and only the HTTP routes are composed.
+ * @evidence contracts/common.md#clear-and-simple-design One public function with a private analysis pipeline.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the same analyzers and composer as the CLI, so both produce one document.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidence contracts/portability.md#os-neutral-implementation Controller source lookup is delegated to ConfigAnalyzer.application; diagnostic filenames use Node path.relative from process.cwd. Route paths and versions remain protocol text rather than native filesystem identity.
+ */
 export namespace NestiaSwaggerComposer {
+  /**
+   * Returns the OpenAPI document of the application in the requested version.
+   *
+   * The document is composed as OpenAPI 3.2 and converted to the configured
+   * older version; every analysis error is collected and thrown together.
+   *
+   * @evidence contracts/common.md#principled-implementation Composition runs at the newest version and `OpenApiConverter.downgradeDocument` produces the older ones, so version differences live in one converter, and a failure of the analysis throws one error that lists every problem.
+   * @evidence contracts/common.md#clear-and-simple-design One function over the shared analyzers and the Swagger generator.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No route is special-cased; the module graph is read through `ConfigAnalyzer.application`.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the returned versions and the error behavior.
+   * @evidence contracts/portability.md#os-neutral-implementation The composer receives an existing application and writes no output file. Its delegated controller discovery obtains native source locations, and its report renders those locations through path.relative; initialize may read package metadata for default info.
+   */
   export const document = async (
     app: INestApplication,
     config: Omit<INestiaConfig.ISwaggerConfig, "output">,
@@ -58,20 +78,16 @@ export namespace NestiaSwaggerComposer {
     if (project.errors.length)
       throw report({ type: "error", errors: project.errors });
 
-    // METADATA COMPONENTS
-    const collection: IMetadataDictionary =
-      TypedHttpRouteAnalyzer.dictionary(controllers);
-
     // CONVERT TO TYPED OPERATIONS
     const routes: ITypedHttpRoute[] = [];
     for (const c of controllers)
       for (const o of c.operations) {
         if (o.protocol !== "http") continue;
         const pathList: Set<string> = new Set();
-        const versions: string[] = VersioningStrategy.merge(project)([
-          ...(c.versions ?? []),
-          ...(o.versions ?? []),
-        ]);
+        const versions: string[] = VersioningStrategy.merge(project)({
+          controller: c.versions,
+          method: o.versions,
+        });
         for (const v of versions)
           for (const prefix of wrapPaths(c.prefixes))
             for (const cPath of wrapPaths(c.paths))
@@ -95,7 +111,6 @@ export namespace NestiaSwaggerComposer {
           ...TypedHttpRouteAnalyzer.analyze({
             controller: c,
             errors: project.errors,
-            dictionary: collection,
             operation: o,
             paths: Array.from(pathList),
           }),
@@ -131,7 +146,8 @@ const report = (props: {
         `${location} - `,
         error.class,
         ...(error.function !== null ? [`.${error.function}()`] : [""]),
-        ...(error.from !== null ? [` from ${error.from}`] : [""]),
+        // an empty origin names no part of the function
+        ...(error.from ? [` from ${error.from}`] : [""]),
         ":\n",
         contents
           .map((c) => {
@@ -139,8 +155,8 @@ const report = (props: {
             else
               return [
                 c.accessor
-                  ? `  - ${c.name}: `
-                  : `  - ${c.name} (${c.accessor}): `,
+                  ? `  - ${c.name} (${c.accessor}): `
+                  : `  - ${c.name}: `,
                 ...c.messages.map((msg) => `    - ${msg}`),
               ].join("\n");
           })
@@ -148,7 +164,9 @@ const report = (props: {
       ].join(""),
     );
   }
-  throw new Error(`Error on NestiaSwaggerComposer.compose():\n${messages}`);
+  throw new Error(
+    `Error on NestiaSwaggerComposer.compose():\n${messages.join("\n\n")}`,
+  );
 };
 
 const wrapPaths = (paths: string[]): string[] =>