@nestia/migrate 14.0.1 → 14.0.3

package/src/internal/ts.ts

@@ -51,24 +51,177 @@ type _TypeReferenceNode = TypeReferenceNode;
 type _UnionTypeNode = UnionTypeNode;
 type _VariableStatement = VariableStatement;
 
+/**
+ * A compatibility stand-in for `import ts from "typescript"`: the one value the
+ * generators still call, and the node types under the names they use.
+ *
+ * @evidence contracts/common.md#principled-implementation The value is the union-type guard, and the namespace aliases map each used compiler type name to the matching node type of the factory package, so existing annotations keep their exact shapes.
+ * @evidence contracts/common.md#clear-and-simple-design One value and one declaration-only namespace of aliases.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It avoids loading the compiler; the guard is implemented on the node kind, not on a patched compiler.
+ * @evidence contracts/common.md#meaningful-documentation The leading comment explains why the shim exists.
+ */
 declare namespace ts {
+  /**
+   * The `Node` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `Node` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type Node = _Node;
+  /**
+   * The `Block` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `Block` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type Block = _Block;
+  /**
+   * The `CallExpression` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `CallExpression` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type CallExpression = _CallExpression;
+  /**
+   * The `ConciseBody` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation A concise body is a block or an expression, the same union the compiler defines.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type ConciseBody = _Block | _Expression;
+  /**
+   * The `Decorator` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `Decorator` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type Decorator = _Decorator;
+  /**
+   * The `Expression` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `Expression` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type Expression = _Expression;
+  /**
+   * The `FunctionDeclaration` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `FunctionDeclaration` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type FunctionDeclaration = _FunctionDeclaration;
+  /**
+   * The `Identifier` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `Identifier` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type Identifier = _Identifier;
+  /**
+   * The `KeywordTypeNode` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `KeywordTypeNode` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type KeywordTypeNode = _KeywordTypeNode;
+  /**
+   * The `MethodDeclaration` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `MethodDeclaration` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type MethodDeclaration = _MethodDeclaration;
+  /**
+   * The `ModuleDeclaration` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `ModuleDeclaration` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type ModuleDeclaration = _ModuleDeclaration;
+  /**
+   * The `ParameterDeclaration` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `ParameterDeclaration` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type ParameterDeclaration = _ParameterDeclaration;
+  /**
+   * The `Statement` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `Statement` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type Statement = _Statement;
+  /**
+   * The `TypeAliasDeclaration` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `TypeAliasDeclaration` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type TypeAliasDeclaration = _TypeAliasDeclaration;
+  /**
+   * The `TypeNode` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `TypeNode` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type TypeNode = _TypeNode;
+  /**
+   * The `TypeReferenceNode` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `TypeReferenceNode` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type TypeReferenceNode = _TypeReferenceNode;
+  /**
+   * The `UnionTypeNode` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `UnionTypeNode` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type UnionTypeNode = _UnionTypeNode;
+  /**
+   * The `VariableStatement` node type under the name the generators use.
+   *
+   * @evidence contracts/common.md#principled-implementation The alias names the `VariableStatement` node type of the factory package.
+   * @evidence contracts/common.md#clear-and-simple-design One alias.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The alias is named after the compiler type it replaces, and the file comment explains the shim.
+   */
   export type VariableStatement = _VariableStatement;
 }
 

package/src/programmers/NestiaMigrateApiFileProgrammer.ts

@@ -8,15 +8,50 @@ import { NestiaMigrateApiFunctionProgrammer } from "./NestiaMigrateApiFunctionPr
 import { NestiaMigrateApiNamespaceProgrammer } from "./NestiaMigrateApiNamespaceProgrammer";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 
+/**
+ * Generates one file of the functional API: the imports, the exports of the
+ * child namespaces, and the functions of the routes at this level.
+ *
+ * @evidence contracts/common.md#principled-implementation Each route contributes its function and its namespace, the imports are collected by one importer and emitted first, and each child namespace is re-exported, so a file is a complete module.
+ * @evidence contracts/common.md#clear-and-simple-design One function over the two per-route programmers and the importer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The output derives from the routes and the configuration.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the file's content.
+ */
 export namespace NestiaMigrateApiFileProgrammer {
+  /**
+   * The input of one API file: the configuration, the components, the namespace
+   * path, the routes, and the child namespaces.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds exactly what a file needs, so files can be generated independently.
+   * @evidence contracts/common.md#clear-and-simple-design A flat 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 lists the fields.
+   */
   export interface IProps {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
+
+    /** Accessor prefix locating this functional API index. */
     namespace: string[];
+
+    /** Operations whose functions belong directly to this index. */
     routes: IHttpMigrateRoute[];
+
+    /** Immediate child namespace names re-exported by this index. */
     children: Set<string>;
   }
 
+  /**
+   * Returns the statements of one API file.
+   *
+   * @evidence contracts/common.md#principled-implementation The relative path to the structures directory is derived from the namespace depth, so imports resolve from every level.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The depth is computed, not hardcoded.
+   * @evidence contracts/common.md#meaningful-documentation The comment states its result.
+   */
   export const write = (props: IProps): ts.Statement[] => {
     const importer: NestiaMigrateImportProgrammer =
       new NestiaMigrateImportProgrammer();

package/src/programmers/NestiaMigrateApiFunctionProgrammer.ts

@@ -12,14 +12,47 @@ import { SuccessStatus } from "../utils/SuccessStatus";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the function of one route in the SDK.
+ *
+ * @evidence contracts/common.md#principled-implementation The function has the connection parameter, the path, query, header, and body parameters in positional or keyword form, and its body calls the plain or the encrypted fetcher, or the simulator when the connection asks for it, and copies response headers when the description asks.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function, one public parameter builder shared with the simulation programmer, and private helpers for the body and the header directives.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The output derives from the route and the configuration, and the header directives are read from the documented tags.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiFunctionProgrammer {
+  /**
+   * The input of one function: the configuration, the components, the importer,
+   * and the route.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds exactly what the function generation needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat 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 lists the fields.
+   */
   export interface IContext {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
+
+    /** File-local import collector shared with the surrounding file writer. */
     importer: NestiaMigrateImportProgrammer;
+
+    /** Analyzed operation, with the accessor chosen for this generation. */
     route: IHttpMigrateRoute;
   }
 
+  /**
+   * Returns the exported async function declaration of the route, with its
+   * description.
+   *
+   * @evidence contracts/common.md#principled-implementation The function name is the last accessor segment, the return type is the namespace's response type or void, and the description comes from the route comment with the path, the accessor, and the author tag.
+   * @evidence contracts/common.md#clear-and-simple-design One expression over the private parts.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names come from the accessor.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (ctx: IContext): ts.FunctionDeclaration =>
     FilePrinter.description(
       factory.createFunctionDeclaration(
@@ -43,6 +76,16 @@ export namespace NestiaMigrateApiFunctionProgrammer {
       writeDescription(ctx.config, ctx.route),
     );
 
+  /**
+   * Returns the parameters of the function: the connection first, then either
+   * one `props` parameter in keyword mode or the path, query, and body
+   * parameters in positional mode.
+   *
+   * @evidence contracts/common.md#principled-implementation The connection type carries the route's header type when it has one, keyword mode adds `props` only when there is something to pass, and an optional body is marked optional.
+   * @evidence contracts/common.md#clear-and-simple-design One function with the two modes as two returns.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The shape follows the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the two modes.
+   */
   export const writeParameterDeclarations = (
     ctx: IContext,
     connectionName?: string,

package/src/programmers/NestiaMigrateApiNamespaceProgrammer.ts

@@ -15,14 +15,47 @@ import { NestiaMigrateApiSimulationProgrammer } from "./NestiaMigrateApiSimulati
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the namespace that accompanies the function of a route: its types,
+ * its metadata, its path builder, and, in simulation mode, its simulator.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace declares the `Props`, `Query`, `Body`, `Headers`, and `Response` types from the schemas, the route metadata the fetcher reads, the `path` function that fills the parameters into the template, and the simulator members.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function, one public path-call builder shared with the simulation programmer, and private helpers per member.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The output derives from the route and the configuration.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiNamespaceProgrammer {
+  /**
+   * The input of one namespace: the configuration, the components, the
+   * importer, and the route.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds exactly what the namespace generation needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat 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 lists the fields.
+   */
   export interface IContext {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
+
+    /** File-local import collector shared with the surrounding file writer. */
     importer: NestiaMigrateImportProgrammer;
+
+    /** Analyzed operation, with the accessor chosen for this generation. */
     route: IHttpMigrateRoute;
   }
 
+  /**
+   * Returns the namespace declaration of a route.
+   *
+   * @evidence contracts/common.md#principled-implementation The members are written in a fixed order: types, metadata, path function, and the random and simulate members when simulation is enabled.
+   * @evidence contracts/common.md#clear-and-simple-design One function composing the private writers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The members follow the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (ctx: IContext): ts.ModuleDeclaration => {
     const types: ts.TypeAliasDeclaration[] = writeTypes(ctx);
     return factory.createModuleDeclaration(
@@ -45,6 +78,15 @@ export namespace NestiaMigrateApiNamespaceProgrammer {
     );
   };
 
+  /**
+   * Returns the call expression of the route's `path` function with the
+   * arguments the configuration selects.
+   *
+   * @evidence contracts/common.md#principled-implementation In keyword mode the arguments are the `props` object and otherwise the path and query parameters in order, so the same call is valid in both modes.
+   * @evidence contracts/common.md#clear-and-simple-design One function shared by the simulator and the namespace.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The arguments follow the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the two argument forms.
+   */
   export const writePathCallExpression = (
     config: INestiaMigrateConfig,
     route: IHttpMigrateRoute,

package/src/programmers/NestiaMigrateApiProgrammer.ts

@@ -8,7 +8,25 @@ import { NestiaMigrateApiFileProgrammer } from "./NestiaMigrateApiFileProgrammer
 import { NestiaMigrateDtoProgrammer } from "./NestiaMigrateDtoProgrammer";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 
+/**
+ * Generates the functional API files and, for an SDK project, the DTO structure
+ * files.
+ *
+ * @evidence contracts/common.md#principled-implementation Routes are grouped by namespace path in a hash map, each parent namespace is given its child, and each namespace becomes one `index.ts`; the DTO files are written per top-level component name.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and two private helpers for the DTO files.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the accessors of the routes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiProgrammer {
+  /**
+   * Returns the map from file path to content of the functional API, with the
+   * DTO files for an SDK project.
+   *
+   * @evidence contracts/common.md#principled-implementation The grouping creates every ancestor namespace so that each level has an index, and the paths differ between the two modes only by their root.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the accessors.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (ctx: INestiaMigrateContext): Record<string, string> => {
     const dict: HashMap<string[], NestiaMigrateApiFileProgrammer.IProps> =
       new HashMap(

package/src/programmers/NestiaMigrateApiSimulationProgrammer.ts

@@ -12,14 +12,48 @@ import { NestiaMigrateApiNamespaceProgrammer } from "./NestiaMigrateApiNamespace
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the mockup simulator members of a route: a random response and a
+ * simulate function that validates the request first.
+ *
+ * @evidence contracts/common.md#principled-implementation The random member calls `typia.random` for the response type, and the simulate function validates the parameters, query, body, and headers with `typia.assert` through the fetcher's simulator, so an invalid simulated request throws the error the real server answers.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions and one private assertion writer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The simulation follows the schemas of the route.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiSimulationProgrammer {
+  /**
+   * The input of the simulation members: the configuration, the components, the
+   * importer, and the route.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds exactly what the generation needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat 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 lists the fields.
+   */
   export interface IContext {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
+
+    /** File-local import collector shared with the surrounding file writer. */
     importer: NestiaMigrateImportProgrammer;
+
+    /** Analyzed operation, with the accessor chosen for this generation. */
     route: IHttpMigrateRoute;
   }
 
+  /**
+   * Returns the `random` constant: a function that returns a random value of
+   * the response type.
+   *
+   * @evidence contracts/common.md#principled-implementation The response schema is written as a type and given to `typia.random`, and a route without a response uses `void`.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The value is produced by typia at run time.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const random = (ctx: IContext) => {
     const output = ctx.route.success
       ? NestiaMigrateSchemaProgrammer.write({
@@ -54,6 +88,15 @@ export namespace NestiaMigrateApiSimulationProgrammer {
     );
   };
 
+  /**
+   * Returns the `simulate` constant: a function with the route's parameters
+   * that validates the request and returns a random response.
+   *
+   * @evidence contracts/common.md#principled-implementation The parameters are those of the real function, the assertions run first, and an unused connection is renamed so the compiler does not report it.
+   * @evidence contracts/common.md#clear-and-simple-design One expression over the shared parameter builder.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The validation is generated from the same schemas as the real function's types.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const simulate = (ctx: IContext): ts.VariableStatement => {
     const caller = () =>
       factory.createCallExpression(

package/src/programmers/NestiaMigrateApiStartProgrammer.ts

@@ -9,15 +9,31 @@ import { FilePrinter } from "../utils/FilePrinter";
 import { NestiaMigrateE2eFunctionProgrammer } from "./NestiaMigrateE2eFileProgrammer";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 
+/**
+ * Generates the `test/start.ts` of an SDK project: a small program that calls
+ * one API function.
+ *
+ * @evidence contracts/common.md#principled-implementation The program builds a connection from the global test settings and the first server of the document, adds the simulate flag when requested, and calls the first route the way the generated e2e tests do, so one command can check that the SDK and a server agree.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and private helpers for the connection, the main function, and the starter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The route is the first one, so the same document always generates the same file.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiStartProgrammer {
+  /**
+   * Returns the `test/start.ts` file of an SDK project.
+   *
+   * @evidence contracts/common.md#principled-implementation The file imports what the body uses, defines `main`, and starts it, exiting with a failure status when it rejects.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The content derives from the document.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (
     context: INestiaMigrateContext,
   ): Record<string, string> => {
     const importer: NestiaMigrateImportProgrammer =
       new NestiaMigrateImportProgrammer();
-    const route: IHttpMigrateRoute | undefined = pick(
-      context.application.routes,
-    );
+    // the first route, so the same document always generates the same file
+    const route: IHttpMigrateRoute | undefined = context.application.routes[0];
     const main: ts.VariableStatement = writeMain(context, importer, route);
     const statements: ts.Statement[] = [
       ...importer.toStatements(
@@ -197,10 +213,3 @@ export namespace NestiaMigrateApiStartProgrammer {
       ],
     );
 }
-
-const pick = <T>(array: T[]): T | undefined => {
-  if (array.length === 0) return undefined;
-  const rand: number = Math.random() * array.length;
-  const index: number = Math.min(array.length - 1, Math.floor(rand));
-  return array[index]!;
-};

package/src/programmers/NestiaMigrateDtoProgrammer.ts

@@ -10,17 +10,50 @@ import { StringUtil } from "../utils/StringUtil";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the DTO type aliases from the component schemas.
+ *
+ * @evidence contracts/common.md#principled-implementation Each component name is normalized into a valid dotted name, the dots become nested namespaces, and each schema becomes an exported type alias with its description and its tags as a comment.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and private builders for the module tree and the alias.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The names derive from the schema names.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateDtoProgrammer {
+  /**
+   * A node of the DTO namespace tree: its name, its children, and the writer of
+   * its alias, or `null` for a namespace without a type of its own.
+   *
+   * @evidence contracts/common.md#principled-implementation The tree mirrors the dotted names of the schemas, so a namespace exists exactly when a name passes through it.
+   * @evidence contracts/common.md#clear-and-simple-design A three-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 the meaning of each member.
+   */
   export interface IModule {
     name: string;
+
+    /** Child segments of qualified schema names, preserving insertion order. */
     children: Map<string, IModule>;
+
+    /** Alias writer for a schema at this node, or null for a namespace alone. */
     programmer:
       | null
       | ((importer: NestiaMigrateImportProgrammer) => ts.TypeAliasDeclaration);
   }
 
+  /**
+   * Returns the root of the DTO tree: a map from the first name segment to its
+   * module.
+   *
+   * @evidence contracts/common.md#principled-implementation Each schema key is split on slashes, its segments are escaped into valid identifiers and joined, and the result is inserted along its dotted path.
+   * @evidence contracts/common.md#clear-and-simple-design One function over one insertion helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names come from the document.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const compose = (props: {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
   }): Map<string, IModule> => {
     const dict: Map<string, IModule> = new Map();

package/src/programmers/NestiaMigrateE2eFileProgrammer.ts

@@ -9,14 +9,47 @@ import { INestiaMigrateConfig } from "../structures/INestiaMigrateConfig";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the e2e test function of one route.
+ *
+ * @evidence contracts/common.md#principled-implementation The function calls the route through the SDK with random arguments made by `typia.random`, including generated headers, and asserts the response with `typia.assert`, so the test checks that the server's answer matches the declared type.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function, one public body writer shared with the start programmer, and a private call writer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The arguments are drawn at run time, and no route is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateE2eFunctionProgrammer {
+  /**
+   * The input of one test function: the configuration, the components, the
+   * importer, and the route.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds exactly what the generation needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat 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 lists the fields.
+   */
   export interface IContext {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
+
+    /** File-local import collector shared with the surrounding file writer. */
     importer: NestiaMigrateImportProgrammer;
+
+    /** Analyzed operation, with the accessor chosen for this generation. */
     route: IHttpMigrateRoute;
   }
 
+  /**
+   * Returns the exported async test function of a route, named `test_api_`
+   * followed by its accessor.
+   *
+   * @evidence contracts/common.md#principled-implementation The name joins `test`, `api`, and the accessor with underscores, so it is unique for a route and matches the prefix that the e2e executor discovers.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The name derives from the accessor.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the naming rule.
+   */
   export const write = (ctx: IContext): ts.FunctionDeclaration =>
     factory.createFunctionDeclaration(
       [
@@ -47,6 +80,15 @@ export namespace NestiaMigrateE2eFunctionProgrammer {
       factory.createBlock(writeBody(ctx), true),
     );
 
+  /**
+   * Returns the statements of the test body: the call with random arguments and
+   * the type assertion of its output.
+   *
+   * @evidence contracts/common.md#principled-implementation The call expression follows the parameter mode of the configuration, and the output is typed by the response schema when there is one.
+   * @evidence contracts/common.md#clear-and-simple-design One function shared with the start programmer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The body follows the route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const writeBody = (ctx: IContext): ts.Statement[] => [
     factory.createVariableStatement(
       [],

package/src/programmers/NestiaMigrateE2eProgrammer.ts

@@ -8,7 +8,23 @@ import { FilePrinter } from "../utils/FilePrinter";
 import { NestiaMigrateE2eFunctionProgrammer } from "./NestiaMigrateE2eFileProgrammer";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 
+/**
+ * Generates the e2e test files, one per route.
+ *
+ * @evidence contracts/common.md#principled-implementation Each route becomes a file whose path depends on the mode and whose imports are resolved through the package name for a monorepo and through the built library path otherwise.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and one private file writer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the accessors.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateE2eProgrammer {
+  /**
+   * Returns the map from file path to content of the e2e tests.
+   *
+   * @evidence contracts/common.md#principled-implementation The file name is `test_api_` plus the accessor, so each route has exactly one file.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names follow the accessors.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (ctx: INestiaMigrateContext): Record<string, string> =>
     Object.fromEntries(
       ctx.application.routes