@nestia/migrate 14.0.1 → 14.0.2

package/src/programmers/NestiaMigrateImportProgrammer.ts

@@ -1,20 +1,48 @@
-import { SyntaxKind, factory } from "@ttsc/factory";
+import { type EntityName, SyntaxKind, factory } from "@ttsc/factory";
 
 import { TypeLiteralFactory } from "../factories/TypeLiteralFactory";
 import ts from "../internal/ts";
 import { FilePrinter } from "../utils/FilePrinter";
 import { MapUtil } from "../utils/MapUtil";
 
+/**
+ * Collects the imports that generated code needs and turns them into import
+ * statements.
+ *
+ * @evidence contracts/common.md#principled-implementation External imports are grouped by library into one clause with an optional default and a set of named instances, DTO imports are grouped by module specifier and emitted type-only, and a DTO is never imported into its own file.
+ * @evidence contracts/common.md#clear-and-simple-design One class with two collections and one emitter; the tag helper builds `typia.tags` references.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The imports follow the code that asks for them.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export class NestiaMigrateImportProgrammer {
   private external_: Map<string, IClause> = new Map();
   private dtos_: Set<string> = new Set();
 
   public constructor() {}
 
+  /**
+   * Reports whether no import has been requested.
+   *
+   * @evidence contracts/common.md#principled-implementation The importer is empty exactly when both collections are empty.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the state.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the meaning.
+   */
   public empty(): boolean {
     return this.external_.size === 0 && this.dtos_.size === 0;
   }
 
+  /**
+   * Requests an import from a library and returns the local name to use.
+   *
+   * The returned name is the first segment of the requested name, so a nested
+   * name such as `tags.Type` imports `tags`.
+   *
+   * @evidence contracts/common.md#principled-implementation A default import replaces the clause's default and an instance import adds a named import, and the first segment of a dotted name is what the code refers to.
+   * @evidence contracts/common.md#clear-and-simple-design One function over one map.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The library and the name come from the caller.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the returned name.
+   */
   public external(props: MigrateImportProgrammer.IProps): string {
     const clause: IClause = MapUtil.take(this.external_)(props.library)(() => ({
       default: null,
@@ -26,19 +54,41 @@ export class NestiaMigrateImportProgrammer {
     return name;
   }
 
+  /**
+   * Requests a DTO import and returns a reference to it, qualified by a
+   * namespace when one is given.
+   *
+   * @evidence contracts/common.md#principled-implementation The DTO is recorded by the first segment of its dotted name, which is the file that exports it, and the returned reference keeps the full name, with the namespace prepended when one is given.
+   * @evidence contracts/common.md#clear-and-simple-design One function over one set.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The name comes from the caller.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the reference.
+   */
   public dto(name: string, namespace?: string): ts.TypeReferenceNode {
-    const file: string = name.split(".")[0]!;
-    this.dtos_.add(file);
+    const segments: string[] = name.split(".");
+    this.dtos_.add(segments[0]!);
     return factory.createTypeReferenceNode(
       namespace?.length
-        ? factory.createQualifiedName(
+        ? segments.reduce<EntityName>(
+            (left, segment) =>
+              factory.createQualifiedName(
+                left,
+                factory.createIdentifier(segment),
+              ),
             factory.createIdentifier(namespace),
-            factory.createIdentifier(file),
           )
         : name,
     );
   }
 
+  /**
+   * Requests the `typia` tags import and returns a reference to a tag with an
+   * optional literal argument.
+   *
+   * @evidence contracts/common.md#principled-implementation The argument is converted to a literal type, so `Minimum<3>` is written as a type reference with the literal.
+   * @evidence contracts/common.md#clear-and-simple-design One function delegating the literal building.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The tag name and the argument come from the caller.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the reference.
+   */
   public tag(type: string, arg?: any): ts.TypeReferenceNode {
     const instance: string = this.external({
       type: "instance",
@@ -51,6 +101,15 @@ export class NestiaMigrateImportProgrammer {
     );
   }
 
+  /**
+   * Returns the import statements: the external imports, a blank line when both
+   * kinds exist, and the type-only DTO imports.
+   *
+   * @evidence contracts/common.md#principled-implementation DTO names are grouped by the specifier that `dtoPath` returns, a name equal to the current file is skipped so a file never imports itself, and package specifiers merge into one clause.
+   * @evidence contracts/common.md#clear-and-simple-design One function with two emit sections.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The specifier rule is the caller's.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result and the self-import rule.
+   */
   public toStatements(
     dtoPath: (name: string) => string,
     current?: string,
@@ -114,10 +173,32 @@ export class NestiaMigrateImportProgrammer {
     ];
   }
 }
+/**
+ * Types of the importer: the properties of an external import request.
+ *
+ * @evidence contracts/common.md#principled-implementation The record names the import kind, the library, and the name.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace with one interface.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It contains types only.
+ * @evidence contracts/common.md#meaningful-documentation The comment names its content.
+ */
 export namespace MigrateImportProgrammer {
+  /**
+   * An external import request: `default` or `instance`, the library, and the
+   * name.
+   *
+   * @evidence contracts/common.md#principled-implementation The kind selects between the default clause and a named import.
+   * @evidence contracts/common.md#clear-and-simple-design A three-field 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 each field.
+   */
   export interface IProps {
+    /** Select the default export or a named import. */
     type: "default" | "instance";
+
+    /** Module specifier emitted in the import declaration. */
     library: string;
+
+    /** Requested binding; named imports use its leading dotted segment. */
     name: string;
   }
 }

package/src/programmers/NestiaMigrateNestControllerProgrammer.ts

@@ -8,13 +8,43 @@ import { FilePrinter } from "../utils/FilePrinter";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateNestMethodProgrammer } from "./NestiaMigrateNestMethodProgrammer";
 
+/**
+ * Generates the source of one NestJS controller.
+ *
+ * @evidence contracts/common.md#principled-implementation The controller class is decorated with `@Controller` and its path, each route becomes a method written by the configured method programmer or the default one, and the DTO types are imported by package name because they live in the API package.
+ * @evidence contracts/common.md#clear-and-simple-design One function; the method programmer is replaceable through the configuration.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The replaceable programmer is a documented extension point.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateNestControllerProgrammer {
+  /**
+   * The input of one controller: the configuration, the components, and the
+   * controller.
+   *
+   * @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 IProps {
+    /** Generation options and an optional controller-method writer. */
     config: INestiaMigrateConfig;
+
+    /** Schemas needed by generated controller method types. */
     components: OpenApi.IComponents;
+
+    /** Controller name, router prefix and grouped operations. */
     controller: INestiaMigrateController;
   }
 
+  /**
+   * Returns the statements of a controller file.
+   *
+   * @evidence contracts/common.md#principled-implementation Blank lines separate the methods, and the imports come first.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The content follows the controller.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (props: IProps): ts.Statement[] => {
     const importer: NestiaMigrateImportProgrammer =
       new NestiaMigrateImportProgrammer();

package/src/programmers/NestiaMigrateNestMethodProgrammer.ts

@@ -17,15 +17,49 @@ import { SuccessStatus } from "../utils/SuccessStatus";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the controller method of one route.
+ *
+ * @evidence contracts/common.md#principled-implementation The method carries `TypedRoute`, `TypedException`, `HumanRoute`, and example decorators as the route requires, one parameter per path, header, query, and body input with the matching typed decorator, and a body that mentions each parameter and returns `typia.random` of the response type.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and private writers for the description, the decorators, and the parameters.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The output derives from the route; the body is a stub that returns random data because the document does not define the behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateNestMethodProgrammer {
+  /**
+   * The input of one method: the configuration, the components, the importer,
+   * the controller, 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 {
+    /** Generation options, including the author tag used on the handler. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas referenced by request and response types. */
     components: OpenApi.IComponents;
+
+    /** Controller-file import collector shared by all its methods. */
     importer: NestiaMigrateImportProgrammer;
+
+    /** Controller prefix removed from this operation's router path. */
     controller: INestiaMigrateController;
+
+    /** Analyzed operation supplying method, schemas and examples. */
     route: IHttpMigrateRoute;
   }
 
+  /**
+   * Returns the method declaration of a route.
+   *
+   * @evidence contracts/common.md#principled-implementation The decorators and the parameters follow the route's HTTP method, path relative to the controller, and inputs.
+   * @evidence contracts/common.md#clear-and-simple-design One function composing the private writers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The method follows the route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (ctx: IContext): ts.MethodDeclaration => {
     const output: ts.TypeNode = ctx.route.success
       ? NestiaMigrateSchemaProgrammer.write({

package/src/programmers/NestiaMigrateNestModuleProgrammer.ts

@@ -4,7 +4,23 @@ import ts from "../internal/ts";
 import { INestiaMigrateController } from "../structures/INestiaMigrateController";
 import { FilePrinter } from "../utils/FilePrinter";
 
+/**
+ * Generates the NestJS module that lists the controllers.
+ *
+ * @evidence contracts/common.md#principled-implementation The module imports every controller from its location and lists them in the `controllers` array of a decorated class.
+ * @evidence contracts/common.md#clear-and-simple-design One function and one private import builder.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The controllers follow the analysis.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateNestModuleProgrammer {
+  /**
+   * Returns the statements of the module file.
+   *
+   * @evidence contracts/common.md#principled-implementation The import paths turn the `src/` prefix of a controller location into `./`, so the module can import from its own directory.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names follow the controllers.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (
     controllers: INestiaMigrateController[],
   ): ts.Statement[] => [

package/src/programmers/NestiaMigrateNestProgrammer.ts

@@ -10,7 +10,24 @@ import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateNestControllerProgrammer } from "./NestiaMigrateNestControllerProgrammer";
 import { NestiaMigrateNestModuleProgrammer } from "./NestiaMigrateNestModuleProgrammer";
 
+/**
+ * Generates the NestJS side of a monorepo project: the module, the controllers,
+ * and the DTO structures.
+ *
+ * @evidence contracts/common.md#principled-implementation The controllers come from the analyzer, each DTO tree becomes a structure file, and a barrel file re-exports every non-empty structure file so the template's module keeps working.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and private helpers for the DTO files and the barrel.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the analysis.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateNestProgrammer {
+  /**
+   * Returns the map from file path to content of the NestJS files.
+   *
+   * @evidence contracts/common.md#principled-implementation The barrel is computed from the generated structure files, sorted by name, so its content is deterministic.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names follow the document.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (
     context: INestiaMigrateContext,
   ): Record<string, string> => {

package/src/programmers/NestiaMigrateSchemaProgrammer.ts

@@ -2,17 +2,33 @@ import { SyntaxKind, factory } from "@ttsc/factory";
 import { NamingConvention, OpenApiTypeChecker } from "@typia/utils";
 import type { OpenApi } from "typia";
 
-import { FormatCheatSheet } from "../factories/FormatCheatSheet";
+import { SUPPORTED_STRING_FORMATS } from "../factories/SupportedStringFormats";
 import { TypeFactory } from "../factories/TypeFactory";
 import ts from "../internal/ts";
 import { FilePrinter } from "../utils/FilePrinter";
 import { StringUtil } from "../utils/StringUtil";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 
+/**
+ * Generates the TypeScript type of an OpenAPI schema.
+ *
+ * @evidence contracts/common.md#principled-implementation The schema kind is decided by the type checker of `@typia/utils`, and each kind becomes a type: constants as literal types, numbers, integers, and strings with their constraints as `typia.tags` intersections, arrays, tuples, objects, references, and unions, with `any` for an unknown schema.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function that dispatches to one private writer per kind.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The dispatch follows the schema kinds of OpenAPI, and no schema name is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateSchemaProgrammer {
   /* -----------------------------------------------------------
     FACADE
   ----------------------------------------------------------- */
+  /**
+   * Returns the type node of a schema.
+   *
+   * @evidence contracts/common.md#principled-implementation An unknown schema is `any`, a `oneOf` becomes a TypeScript union, integer formats outside the supported four use the migration default `int64`, a binary string becomes `File`, and known string formats become typia tags. TypeScript unions do not encode oneOf exclusivity, and unsupported formats impose no generated constraint.
+   * @evidence contracts/common.md#clear-and-simple-design One function with an ordered chain of schema kind tests.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Schema-kind dispatch applies uniformly; the int64 fallback and supported-format table are generator policies rather than constraints supplied by the document.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (props: {
     components: OpenApi.IComponents;
     importer: NestiaMigrateImportProgrammer;
@@ -209,8 +225,7 @@ export namespace NestiaMigrateSchemaProgrammer {
       intersection.push(props.importer.tag("Pattern", props.schema.pattern));
     if (
       props.schema.format !== undefined &&
-      (FormatCheatSheet as Record<string, string>)[props.schema.format] !==
-        undefined
+      SUPPORTED_STRING_FORMATS.has(props.schema.format)
     )
       intersection.push(props.importer.tag("Format", props.schema.format));
     if (props.schema.contentMediaType !== undefined)
@@ -267,11 +282,13 @@ export namespace NestiaMigrateSchemaProgrammer {
       props.schema.additionalItems !== null
         ? [
             factory.createRestTypeNode(
-              write({
-                components: props.components,
-                importer: props.importer,
-                schema: props.schema.additionalItems,
-              }),
+              factory.createArrayTypeNode(
+                write({
+                  components: props.components,
+                  importer: props.importer,
+                  schema: props.schema.additionalItems,
+                }),
+              ),
             ),
           ]
         : props.schema.additionalItems === true

package/src/structures/INestiaMigrateConfig.ts

@@ -1,15 +1,41 @@
 import ts from "../internal/ts";
 import { NestiaMigrateNestMethodProgrammer } from "../programmers/NestiaMigrateNestMethodProgrammer";
 
+/**
+ * Options of the migration: simulation, e2e tests, the package name, keyword
+ * parameters, the author tag, and a replaceable controller method programmer.
+ *
+ * @evidence contracts/common.md#principled-implementation The flags choose which parts are generated and the parameter style, the package name replaces the placeholder in every file, and the programmer option lets a caller generate controller methods differently.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record whose optional members are the extension points.
+ * @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 options.
+ */
 export interface INestiaMigrateConfig {
+  /** Include runtime request validation and random-response simulator members. */
   simulate: boolean;
+
+  /** Emit a generated test feature for each migrated operation. */
   e2e: boolean;
+
+  /** Replace the template package placeholder; omission retains the placeholder. */
   package?: string;
+
+  /**
+   * Use a props object when true; false or omission selects positional
+   * parameters.
+   */
   keyword?: boolean;
+
+  /** Override the generated declaration attribution tag and its text. */
   author?: {
     tag: string;
     value: string;
   };
+
+  /**
+   * Replace controller method emission while retaining the surrounding
+   * controller.
+   */
   programmer?: {
     controllerMethod?: (
       ctx: NestiaMigrateNestMethodProgrammer.IContext,

package/src/structures/INestiaMigrateContext.ts

@@ -2,8 +2,25 @@ import { IHttpMigrateApplication } from "@typia/interface";
 
 import { INestiaMigrateConfig } from "./INestiaMigrateConfig";
 
+/**
+ * The shared input of the programmers: the mode, the analyzed application, and
+ * the configuration.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is built once per migration, so every programmer sees the same routes and options.
+ * @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 lists the members.
+ */
 export interface INestiaMigrateContext {
+  /** Select backend/API workspace output or a standalone SDK project. */
   mode: "nest" | "sdk";
+
+  /**
+   * Generation-local route/accessor copies backed by the shared analyzed
+   * document.
+   */
   application: IHttpMigrateApplication;
+
+  /** Options used consistently by each programmer in this generation. */
   config: INestiaMigrateConfig;
 }

package/src/structures/INestiaMigrateController.ts

@@ -1,8 +1,24 @@
 import { IHttpMigrateRoute } from "@typia/interface";
 
+/**
+ * A controller to generate: its name, its path, its source location, and its
+ * routes.
+ *
+ * @evidence contracts/common.md#principled-implementation The record is the output of the analyzer and the input of the controller programmer.
+ * @evidence contracts/common.md#clear-and-simple-design A four-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 lists the members.
+ */
 export interface INestiaMigrateController {
+  /** Class identifier shared by its declaration, filename and module import. */
   name: string;
+
+  /** Shared router path prefix, including router escapes for literal characters. */
   path: string;
+
+  /** Slash-separated source directory relative to the backend package. */
   location: string;
+
+  /** Operations grouped into this controller, in document order. */
   routes: IHttpMigrateRoute[];
 }

package/src/structures/INestiaMigrateFile.ts

@@ -1,5 +1,18 @@
+/**
+ * A generated file: its directory, its name, and its content.
+ *
+ * @evidence contracts/common.md#principled-implementation The record separates the location from the name so the writers can join them per mode.
+ * @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 lists the members.
+ */
 export interface INestiaMigrateFile {
+  /** Slash-separated output directory relative to the generated project root. */
   location: string;
+
+  /** Filename within location. */
   file: string;
+
+  /** Complete source text written without another generation step. */
   content: string;
 }

package/src/utils/FilePrinter.ts

@@ -7,7 +7,24 @@ import {
 
 import ts from "../internal/ts";
 
+/**
+ * Helpers that turn statements and comments into file text.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace attaches a JSDoc comment to a node, builds a blank line, and prints a file from statements.
+ * @evidence contracts/common.md#clear-and-simple-design Three small functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The comment text is escaped so it cannot end the comment early.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace FilePrinter {
+  /**
+   * Attaches a JSDoc comment made from the text to the node, and leaves the
+   * node alone when the text is empty.
+   *
+   * @evidence contracts/common.md#principled-implementation Line endings are normalized, each line is prefixed, and every comment terminator in the text is replaced by an escaped form, so a description can never end the comment early and inject code.
+   * @evidence contracts/common.md#clear-and-simple-design One function with an early return.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The escaping applies to every line.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the empty case and the escaping.
+   */
   export const description = <Node extends ts.Node>(
     node: Node,
     comment: string,
@@ -33,9 +50,25 @@ export namespace FilePrinter {
     return node;
   };
 
+  /**
+   * Builds a statement that prints as a blank line.
+   *
+   * @evidence contracts/common.md#principled-implementation The printer emits the identifier text as it is, so an identifier holding a newline produces an empty line between statements.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is the way the printer offers to space statements.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the statement prints.
+   */
   export const newLine = () =>
     factory.createExpressionStatement(factory.createIdentifier("\n"));
 
+  /**
+   * Prints the statements as a file, with an optional text at the top.
+   *
+   * @evidence contracts/common.md#principled-implementation The statements are printed by the factory package's printer, so the output is the source of the syntax tree.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It prints what it is given.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the top text.
+   */
   export const write = (props: {
     statements: ts.Statement[];
     top?: string;

package/src/utils/MapUtil.ts

@@ -1,10 +1,26 @@
+/**
+ * Helpers for maps.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the get-or-create helper.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain helper.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace MapUtil {
+  /**
+   * Returns the value of a key, creating and storing it with the generator when
+   * the key is absent.
+   *
+   * @evidence contracts/common.md#principled-implementation Presence is tested with `has`, so a stored falsy value is returned and not created again, and the generator runs once per key.
+   * @evidence contracts/common.md#clear-and-simple-design One check, one generator call, and one store.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The stored value is returned as it is.
+   * @evidence contracts/common.md#meaningful-documentation The comment states when the generator runs.
+   */
   export const take =
     <Key, T>(dict: Map<Key, T>) =>
     (key: Key) =>
     (generator: () => T): T => {
-      const oldbie: T | undefined = dict.get(key);
-      if (oldbie) return oldbie;
+      if (dict.has(key)) return dict.get(key) as T;
 
       const value: T = generator();
       dict.set(key, value);

package/src/utils/PathTemplate.ts

@@ -1,6 +1,22 @@
 import { IHttpMigrateRoute } from "@typia/interface";
 
+/**
+ * Splits a route path template into literal and parameter segments.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace scans the template for `{name}` placeholders and matches each with the route's parameter of that name.
+ * @evidence contracts/common.md#clear-and-simple-design One type and one function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The scan is by the template syntax.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace PathTemplate {
+  /**
+   * A segment of a path: a literal text or a parameter.
+   *
+   * @evidence contracts/common.md#principled-implementation The union is discriminated by `type`, so a consumer handles each case once.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member union.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the two cases.
+   */
   export type ISegment =
     | { type: "literal"; value: string }
     | { type: "param"; parameter: IHttpMigrateRoute.IParameter };
@@ -11,7 +27,13 @@ export namespace PathTemplate {
    * parameter name. The emended path (`/files/:id.json`) cannot be split back:
    * its `:id.json` could name `id` or `id.json`, and a name such as `item-id`
    * would read as `item` followed by `-id`. It always starts with `/`, as the
-   * emended path does.
+   * emended path does. A placeholder without a matching route parameter remains
+   * literal text; adjacent literals are merged.
+   *
+   * @evidence contracts/common.md#principled-implementation The scan uses a regular expression over the placeholders and joins the text between them, and merging adjacent literals keeps the segment list minimal.
+   * @evidence contracts/common.md#clear-and-simple-design One function with one helper for merging.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It never drops text of the template.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the merging and the unmatched placeholder rule.
    */
   export const segments = (route: IHttpMigrateRoute): ISegment[] => {
     const path: string = route.path.startsWith("/")

package/src/utils/RequestBody.ts

@@ -1,10 +1,23 @@
 import { IHttpMigrateRoute } from "@typia/interface";
 
+/**
+ * Helpers about the request body of a route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the optional-body predicate.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a plain helper.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace RequestBody {
   /**
    * Whether the route's body may be omitted: a JSON or text body the document
    * does not require. The SDK's positional and keyword functions and the Nest
    * controller all read this one rule.
+   *
+   * @evidence contracts/common.md#principled-implementation The requirement flag is read from the operation and only an explicit `false` makes the body optional.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the document.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the condition.
    */
   export const optional = (route: IHttpMigrateRoute): boolean =>
     route.body !== null &&