@nestia/sdk 14.0.1 → 14.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/sdk",
-  "version": "14.0.1",
+  "version": "14.0.2",
   "description": "Nestia SDK and Swagger generator",
   "main": "lib/index.js",
   "bin": {
@@ -56,11 +56,12 @@
     "ttsc": "^0.28.1",
     "tstl": "^3.0.0",
     "typia": "15.0.0",
-    "@nestia/core": "^14.0.1",
-    "@nestia/fetcher": "^14.0.1"
+    "@babel/parser": "^7.29.8",
+    "@nestia/core": "^14.0.2",
+    "@nestia/fetcher": "^14.0.2"
   },
   "peerDependencies": {
-    "@nestia/core": "^14.0.1"
+    "@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 -count=1 ./..."
+    "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`.
@@ -265,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(
@@ -84,6 +120,17 @@ 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(
@@ -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(
@@ -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,6 +268,8 @@ export class NestiaSdkApplication {
             ...TypedMcpRouteAnalyzer.analyze({
               controller: c,
               operation: o,
+              clone: project.config.clone,
+              errors: project.errors,
             }),
           );
           continue;
@@ -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)

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,10 +78,6 @@ 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)
@@ -95,7 +111,6 @@ export namespace NestiaSwaggerComposer {
           ...TypedHttpRouteAnalyzer.analyze({
             controller: c,
             errors: project.errors,
-            dictionary: collection,
             operation: o,
             paths: Array.from(pathList),
           }),

package/src/analyses/AccessorAnalyzer.ts

@@ -6,7 +6,33 @@ import { ITypedWebSocketRoute } from "../structures/ITypedWebSocketRoute";
 
 type AnyRoute = ITypedHttpRoute | ITypedWebSocketRoute | ITypedMcpRoute;
 
+/**
+ * Assigns each route the accessor path under which the generated SDK exposes
+ * it.
+ *
+ * @evidence contracts/common.md#principled-implementation The accessors are shrunk where a name repeats, escaped into valid unique identifiers, shrunk again, and each route is renamed to its last accessor segment.
+ * @evidence contracts/common.md#clear-and-simple-design One public function over three private passes.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The passes follow the accessor structure and no route or controller name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: For R routes of at most D accessor segments, the prefix maps avoid repeated route-to-route searches. Prefix slicing and joining costs O(R D²) character work before collision escapes; collisions add probes and longer names. Two shrink passes are required around escaping because escaping changes the names being shrunk.
+ * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+ * bound retention and release resources: This operation owns only invocation-local values, with no retained cache, handle or background task.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation AccessorAnalyzer 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 AccessorAnalyzer {
+  /**
+   * Rewrites the accessor of every route in place so that accessors are valid,
+   * unique, and as short as they can be.
+   *
+   * @evidence contracts/common.md#principled-implementation Segments that repeat their parent are removed when no sibling shares the parent, non-identifier characters become underscores, a segment that collides with an existing accessor gets an underscore prefix, and the route name becomes the last segment.
+   * @evidence contracts/common.md#clear-and-simple-design One function that runs the passes in a fixed order.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rules apply to every route, and reserved names are computed from the routes themselves.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the passes and the in-place rewrite.
+   * efficient algorithms: For R routes of at most D accessor segments, the prefix maps avoid repeated route-to-route searches. Prefix slicing and joining costs O(R D²) character work before collision escapes; collisions add probes and longer names. Two shrink passes are required around escaping because escaping changes the names being shrunk.
+   * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+   * bound retention and release resources: This operation owns only invocation-local values, with no retained cache, handle or background task.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation AccessorAnalyzer.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 = (routes: Array<AnyRoute>) => {
     shrink(routes);
     variable(routes);

package/src/analyses/ConfigAnalyzer.ts

@@ -6,20 +6,49 @@ import { Module } from "@nestjs/core/injector/module";
 import fs from "fs";
 import getFunctionLocation from "get-function-location";
 import path from "path";
-import { HashMap, Pair, Singleton } from "tstl";
+import { HashMap } from "tstl";
 import { pathToFileURL } from "url";
 
 import { INestiaConfig } from "../INestiaConfig";
-import { SdkGenerator } from "../generates/SdkGenerator";
 import { INestiaSdkInput } from "../structures/INestiaSdkInput";
-import { ArrayUtil } from "../utils/ArrayUtil";
 import { EmittedJavaScriptPatcher } from "../utils/EmittedJavaScriptPatcher";
 import { MapUtil } from "../utils/MapUtil";
+import { PathUtil } from "../utils/PathUtil";
+import { SdkInputFilter } from "../utils/SdkInputFilter";
 import { SourceFinder } from "../utils/SourceFinder";
+import { TemporaryDirectory } from "../utils/TemporaryDirectory";
 import { TsConfigReader } from "../utils/TsConfigReader";
 import { TtscExecutor } from "../utils/TtscExecutor";
 
+/**
+ * Finds the controllers a configuration names, either by compiling and
+ * importing sources or by reading a running application.
+ *
+ * @evidence contracts/common.md#principled-implementation Sources are compiled once through ttsc into a temporary directory, imported, and the exports that carry the Nest `path` metadata are the controllers; an application is read from its module container; results are memoized per configuration object in a weakly keyed map, so a configuration the watcher reloads releases its entry with the object.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions and a private runtime compiler; the output-specific bundle filter comes from SdkInputFilter and configuration/runtime materializations share the owned-child cleanup registry.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The generated SDK's own files are excluded from the input by the bundle list of the SDK, not by name, and the container is read through internals, as noted at `application`.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * efficient algorithms: Discovery traverses candidate files once, compiles one runtime project and inspects every exported value; work scales with source/compiler input and export population. Application input instead traverses container controllers and resolves each unique class location.
+ * reuse equivalent work: The promise cache shares concurrent and completed analyses for the same config object. It assumes that object, its input sources and application state remain unchanged during its lifetime; callers must supply a fresh config object after changes. Bundle exclusion shares only installed asset descriptions and derives native/realpath roots separately for each output; distinct outputs never reuse one captured prefix.
+ * bound retention and release resources: The weakly keyed input map does not retain released config objects, but emitted directories are registered until owned generation cleanup or process exit. Imported CommonJS/ESM modules remain in the hosting Node loader; direct programmatic callers have no per-generation unload guarantee. CLI watch generations isolate this state in a short-lived child.
+ * @evidence contracts/portability.md#os-neutral-implementation Source/controller identity is obtained from Node path/file-URL conversion, module resolution and native fs. Compiler projects use explicit cwd and native paths; emitted module imports use file URLs. Route prefix/version spelling is kept as protocol text, not treated as filesystem identity.
+ */
 export namespace ConfigAnalyzer {
+  /**
+   * Returns the analyzed input of a configuration: the controllers with their
+   * files and the global prefix and versioning options.
+   *
+   * The result is cached per configuration object.
+   *
+   * @evidence contracts/common.md#principled-implementation A function input is asked for the application and read as a running app; otherwise the matched TypeScript sources are compiled and imported, and the memo stores the promise so concurrent callers share one compilation.
+   * @evidence contracts/common.md#clear-and-simple-design One function delegating to `application` or to the runtime compiler.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The cache is keyed by the identity of the configuration object, so a different or reloaded configuration object is never served another's result; one object keeps its first result, which is the contract of a configuration that is not mutated between generations.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the two input forms and the caching.
+   * efficient algorithms: Discovery traverses candidate files once, compiles one runtime project and inspects every exported value; work scales with source/compiler input and export population. Application input instead traverses container controllers and resolves each unique class location.
+   * reuse equivalent work: The promise cache shares concurrent and completed analyses for the same config object. It assumes that object, its input sources and application state remain unchanged during its lifetime; callers must supply a fresh config object after changes. Bundle exclusion shares only installed asset descriptions and derives native/realpath roots separately for each output; distinct outputs never reuse one captured prefix.
+   * bound retention and release resources: The weakly keyed input map does not retain released config objects, but emitted directories are registered until owned generation cleanup or process exit. Imported CommonJS/ESM modules remain in the hosting Node loader; direct programmatic callers have no per-generation unload guarantee. CLI watch generations isolate this state in a short-lived child.
+   * @evidence contracts/portability.md#os-neutral-implementation Source/controller identity is obtained from Node path/file-URL conversion, module resolution and native fs. Compiler projects use explicit cwd and native paths; emitted module imports use file URLs. Route prefix/version spelling is kept as protocol text, not treated as filesystem identity.
+   */
   export const input = async (
     config: INestiaConfig,
   ): Promise<INestiaSdkInput> => {
@@ -37,7 +66,7 @@ export namespace ConfigAnalyzer {
           typeof config.input === "object" && !Array.isArray(config.input)
             ? (config.input.exclude ?? [])
             : [],
-        filter: filter(config),
+        filter: await SdkInputFilter.create(config.output),
       });
       const runtime: RuntimeCompiler = await RuntimeCompiler.compile(sources);
       const controllers: INestiaSdkInput.IController[] = [];
@@ -62,6 +91,19 @@ export namespace ConfigAnalyzer {
     });
   };
 
+  /**
+   * Reads the controllers, the global prefix, and the versioning options of a
+   * running NestJS application.
+   *
+   * @evidence contracts/common.md#principled-implementation The controllers come from the module container with their module paths, their files from the location of each class, decoded from the `file:` URL, and the prefix and versioning options from the application's configuration.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts NestJS exposes no public accessor for the container or the configuration, so the function reads `app.container` and `app.config`; this is the one foreign-internal read of the package and stays a stated limit.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is read.
+   * efficient algorithms: The container is traversed once and a hash map groups each class with its module prefixes, so location lookup occurs once per unique controller class.
+   * reuse equivalent work: This invocation computes its own result and coordinates no completed or in-flight computation across requests.
+   * bound retention and release resources: The invocation retains local module/controller collections until it returns. The running application and its controllers remain caller-owned; this reader neither starts nor closes the app.
+   * @evidence contracts/portability.md#os-neutral-implementation Source/controller identity is obtained from Node path/file-URL conversion, module resolution and native fs. Compiler projects use explicit cwd and native paths; emitted module imports use file URLs. Route prefix/version spelling is kept as protocol text, not treated as filesystem identity.
+   */
   export const application = async (
     app: INestApplication,
   ): Promise<INestiaSdkInput> => {
@@ -88,7 +130,7 @@ export namespace ConfigAnalyzer {
       const file: string | null =
         (await getFunctionLocation(it.first))?.source ?? null;
       if (file === null) continue;
-      const location: string = normalize_file(file);
+      const location: string = PathUtil.location(file);
       if (location.length === 0) continue;
       controllers.push({
         class: it.first,
@@ -120,7 +162,7 @@ export namespace ConfigAnalyzer {
     };
   };
 }
-const memory = new Map<INestiaConfig, Promise<INestiaSdkInput>>();
+const memory = new WeakMap<INestiaConfig, Promise<INestiaSdkInput>>();
 class RuntimeCompiler {
   private constructor(
     private readonly cwd: string,
@@ -135,11 +177,7 @@ class RuntimeCompiler {
       ".nestia",
       "runtime",
     );
-    await fs.promises.mkdir(runtimeRoot, { recursive: true });
-    ensureRuntimeCleanup(runtimeRoot);
-    const outDir: string = await fs.promises.mkdtemp(
-      path.join(runtimeRoot, "run-"),
-    );
+    const outDir: string = TemporaryDirectory.create(runtimeRoot, "run-");
     const project: string = path.join(
       cwd,
       `.nestia.runtime.${process.pid}.${Date.now()}.json`,
@@ -195,42 +233,6 @@ class RuntimeCompiler {
   }
 }
 
-const RUNTIME_ROOTS: Set<string> = new Set();
-let RUNTIME_CLEANUP_REGISTERED: boolean = false;
-
-const ensureRuntimeCleanup = (runtimeRoot: string): void => {
-  RUNTIME_ROOTS.add(runtimeRoot);
-  if (RUNTIME_CLEANUP_REGISTERED === true) return;
-  RUNTIME_CLEANUP_REGISTERED = true;
-  const sweep = (): void => {
-    for (const location of RUNTIME_ROOTS)
-      fs.rmSync(location, { force: true, recursive: true });
-  };
-  process.once("exit", sweep);
-  // process.once("exit", …) does not fire on SIGINT/SIGTERM. Without these
-  // handlers a Ctrl-C during codegen leaves `run-*` mkdtemp directories
-  // behind under node_modules/.nestia/runtime/ until a subsequent clean exit.
-  // The module-level RUNTIME_CLEANUP_REGISTERED flag above guards against
-  // re-entrancy within this module; we deliberately do NOT gate on
-  // `process.listenerCount(signal) > 0` because NestiaConfigLoader's parallel
-  // sweep registers first, and that gate would skip our registration —
-  // leaving RUNTIME_ROOTS unswept on Ctrl-C while config-loader cleans up.
-  // Windows note: `process.kill(pid, "SIGINT")` calls TerminateProcess
-  // rather than re-raising through the listener queue, so the handler
-  // cascade documented above only holds on POSIX. On Windows, whichever
-  // module registers FIRST runs its sweep and the second is skipped —
-  // RUNTIME_ROOTS cleanup is best-effort there. SIGHUP is a no-op for
-  // most common code paths on Windows (Node fires it on console-close
-  // and exits within seconds).
-  const onSignal = (signal: NodeJS.Signals): void => {
-    sweep();
-    process.kill(process.pid, signal);
-  };
-  for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
-    process.once(signal, onSignal);
-  }
-};
-
 type RuntimePlugin = Record<string, unknown> & { transform?: unknown };
 
 const sdkTransformEnv = (): NodeJS.ProcessEnv =>
@@ -298,47 +300,7 @@ const normalizeProjectPath = (project: string | undefined): string => {
   return path.isAbsolute(next) || next.startsWith(".") ? next : `./${next}`;
 };
 
-const normalize_file = (str: string) =>
-  str.substring(
-    str.startsWith("file:///")
-      ? process.cwd()[0] === "/"
-        ? 7
-        : 8
-      : str.startsWith("file://")
-        ? 7
-        : 0,
-  );
-
-const filter =
-  (config: INestiaConfig) =>
-  async (location: string): Promise<boolean> =>
-    SourceFinder.isTypeScriptSource(location) &&
-    (config.output === undefined ||
-      (location.indexOf(path.join(config.output, "functional")) === -1 &&
-        (await (
-          await bundler.get(config.output)
-        )(location))) === false);
-
 const dynamicImport: (specifier: string) => Promise<any> = Function(
   "specifier",
   "return import(specifier);",
 ) as (specifier: string) => Promise<any>;
-
-const bundler = new Singleton(async (output: string) => {
-  const assets: string[] = await fs.promises.readdir(SdkGenerator.BUNDLE_PATH);
-  const tuples: Pair<string, boolean>[] = await ArrayUtil.asyncMap(
-    assets,
-    async (file) => {
-      const relative: string = path.join(output, file);
-      const location: string = path.join(SdkGenerator.BUNDLE_PATH, file);
-      const stats: fs.Stats = await fs.promises.stat(location);
-      return new Pair(relative, stats.isDirectory());
-    },
-  );
-  return async (file: string): Promise<boolean> => {
-    for (const it of tuples)
-      if (it.second === false && file === it.first) return true;
-      else if (it.second === true && file.indexOf(it.first) === 0) return true;
-    return false;
-  };
-});