@nestia/migrate 14.0.0 → 14.0.2

package/src/factories/ExpressionFactory.ts

@@ -9,8 +9,22 @@ import {
  * Numeric-literal helper that handles negative values via a leading
  * `MinusToken` prefix unary, matching how the TypeScript factory itself emits
  * negative numeric literals.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the number literal builder that the generators need.
+ * @evidence contracts/common.md#clear-and-simple-design One function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 export namespace ExpressionFactory {
+  /**
+   * Builds a numeric literal, using a prefix minus for a negative value,
+   * because a negative numeric literal is not a valid node.
+   *
+   * @evidence contracts/common.md#principled-implementation TypeScript represents a negative number as a prefix unary minus applied to a positive literal, so the function builds that shape for values below zero and a plain literal otherwise.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the syntax tree grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the negative case.
+   */
   export const number = (
     value: number,
   ): NumericLiteral | PrefixUnaryExpression =>

package/src/factories/IdentifierFactory.ts

@@ -19,11 +19,21 @@ const isVariableName = (str: string): boolean => VARIABLE_REGEX.test(str);
 /**
  * Identifier and member-access helpers. The surface kept here is the subset
  * nestia generators actually call (`identifier`, `access`, `parameter`).
+ *
+ * @evidence contracts/common.md#principled-implementation The functions decide between an identifier and a string literal by the syntax of the name, so any string can be used as a key.
+ * @evidence contracts/common.md#clear-and-simple-design Three small functions and one private predicate.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The variable-name test is a regular expression of the language's identifier syntax, which is inlined so that the package need not load a larger namespace.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 export namespace IdentifierFactory {
   /**
    * Build an identifier or string literal depending on whether `name` is a
    * valid JavaScript identifier.
+   *
+   * @evidence contracts/common.md#principled-implementation The name is tested against the identifier grammar `[A-Za-z_$][A-Za-z0-9_$]*`, which is conservative: a valid name outside it, such as one with non-ASCII letters, becomes a quoted key, which is equivalent.
+   * @evidence contracts/common.md#clear-and-simple-design One conditional.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The test applies to every name.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the two results.
    */
   export const identifier = (name: string): Identifier | StringLiteral =>
     isVariableName(name)
@@ -33,6 +43,11 @@ export namespace IdentifierFactory {
   /**
    * Member access on `input` by `key`. Falls back to element access when the
    * key is not a valid identifier.
+   *
+   * @evidence contracts/common.md#principled-implementation The postfix is built by `identifier`, and its kind selects the property form or the element form, with the chain token added when requested.
+   * @evidence contracts/common.md#clear-and-simple-design One function delegating the naming rule.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It never concatenates source text.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the forms.
    */
   export const access = (
     input: Expression,
@@ -60,6 +75,11 @@ export namespace IdentifierFactory {
   /**
    * Parameter declaration with default `any` type when the caller omits one.
    * Passing a `QuestionToken` as `init` marks the parameter optional.
+   *
+   * @evidence contracts/common.md#principled-implementation An initializer that is the question token becomes the optional marker and is not an initializer, and any other initializer is passed through.
+   * @evidence contracts/common.md#clear-and-simple-design One function with one branch.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the optional marker and the default type.
    */
   export const parameter = (
     name: string | Identifier,

package/src/factories/LiteralFactory.ts

@@ -16,10 +16,26 @@ const isNode = (value: unknown): value is Expression =>
 
 /**
  * Recursive value-to-AST-literal builder. Hands back already-AST inputs
- * unchanged (so callers can mix factory output with raw JS values inside the
- * same object/array), and emits the appropriate literal node otherwise.
+ * unchanged for arrow functions, calls and identifiers (so callers can mix
+ * those factory expressions with raw values inside objects/arrays), and emits
+ * the appropriate literal node otherwise.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps null, booleans, numbers, strings, bigint text, arrays and object entries to literal expressions, passes through the three accepted AST kinds, maps functions to undefined and refuses unsupported primitive types.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and two private helpers for containers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is by type, with no value special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 export namespace LiteralFactory {
+  /**
+   * Builds the expression of a value: `null`, a boolean, a number, a string, a
+   * bigint as its text, an array, an object without its `undefined` members, or
+   * an expression node as it is.
+   *
+   * @evidence contracts/common.md#principled-implementation The value is dispatched by type in a fixed order; nodes of the kinds arrow function, call, and identifier pass through, functions become `undefined`, and an unsupported type is a `TypeError`, so the result is total over the listed types.
+   * @evidence contracts/common.md#clear-and-simple-design One function with one branch per type.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The dispatch is general, and a bigint becomes text because a literal bigint is not supported by the target syntax here.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the mapping.
+   */
   export const write = (input: any): Expression => {
     if (input === null) return factory.createNull();
     if (isNode(input) && PASSTHROUGH_KINDS.has(input.kind)) return input;

package/src/factories/StatementFactory.ts

@@ -8,8 +8,24 @@ import {
 
 import { TypeFactory } from "./TypeFactory";
 
-/** Variable-statement helpers. `constant` emits `const`, `mut` emits `let`. */
+/**
+ * Variable-statement helpers. `constant` emits `const`, `mut` emits `let`.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace builds `let` and `const` statements from a name, an optional type, and an optional value.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace StatementFactory {
+  /**
+   * Builds a `let` statement; a declaration without a type and without an
+   * initializer is typed `any`.
+   *
+   * @evidence contracts/common.md#principled-implementation A `let` without both a type and an initializer would be implicitly any, so the type is stated explicitly in that case.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the default type.
+   */
   export const mut = (props: {
     name: string;
     type?: TypeNode | undefined;
@@ -34,6 +50,15 @@ export namespace StatementFactory {
       ),
     );
 
+  /**
+   * Builds a `const` statement from a name, an optional type, and an optional
+   * value.
+   *
+   * @evidence contracts/common.md#principled-implementation The declaration list carries the const flag and the given parts.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states its inputs.
+   */
   export const constant = (props: {
     name: string;
     type?: TypeNode | undefined;

package/src/factories/SupportedStringFormats.ts

@@ -0,0 +1,29 @@
+/**
+ * The string formats of the OpenAPI document that the typia `Format` tag
+ * validates, so a schema carrying one of them is generated as a `Format` tag
+ * and a schema carrying any other format stays a plain `string`.
+ */
+export const SUPPORTED_STRING_FORMATS: ReadonlySet<string> = new Set([
+  "byte",
+  "password",
+  "regex",
+  "uuid",
+  "email",
+  "hostname",
+  "idn-email",
+  "idn-hostname",
+  "iri",
+  "iri-reference",
+  "ipv4",
+  "ipv6",
+  "uri",
+  "uri-reference",
+  "uri-template",
+  "url",
+  "date-time",
+  "date",
+  "time",
+  "duration",
+  "json-pointer",
+  "relative-json-pointer",
+]);

package/src/factories/TypeFactory.ts

@@ -6,6 +6,11 @@ import { type KeywordTypeNode, SyntaxKind, factory } from "@ttsc/factory";
  * Wraps {@link factory.createKeywordTypeNode} with a name-based interface so
  * generator code reads as `TypeFactory.keyword("any")` instead of selecting the
  * `SyntaxKind.AnyKeyword` token by hand.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps the names of the nine keyword types to their syntax kinds.
+ * @evidence contracts/common.md#clear-and-simple-design One table, one type, and one function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
  */
 export namespace TypeFactory {
   const KEYWORDS = {
@@ -20,8 +25,24 @@ export namespace TypeFactory {
     undefined: SyntaxKind.UndefinedKeyword,
   } as const;
 
+  /**
+   * The names of the supported keyword types.
+   *
+   * @evidence contracts/common.md#principled-implementation The type is the key set of the table that maps names to syntax kinds, so a new keyword is one table entry.
+   * @evidence contracts/common.md#clear-and-simple-design One derived type.
+   * @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 set.
+   */
   export type Keyword = keyof typeof KEYWORDS;
 
+  /**
+   * Builds the keyword type node of a keyword name.
+   *
+   * @evidence contracts/common.md#principled-implementation The name is looked up in the table, so an unsupported name is a compile error.
+   * @evidence contracts/common.md#clear-and-simple-design One lookup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the type grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states its input.
+   */
   export const keyword = (type: Keyword): KeywordTypeNode =>
     factory.createKeywordTypeNode(KEYWORDS[type]);
 }

package/src/factories/TypeLiteralFactory.ts

@@ -3,7 +3,25 @@ import { NamingConvention } from "@typia/utils";
 
 import ts from "../internal/ts";
 
+/**
+ * Builds type nodes from JavaScript values, so a value can be written as a
+ * literal type.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps booleans, numbers, strings, null, arrays as tuples, and objects as type literals, and anything else to `any`.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and small private builders per kind.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is by type, with no value special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace TypeLiteralFactory {
+  /**
+   * Builds the literal type of a value: a literal for a primitive, a tuple for
+   * an array, a type literal for an object, and `any` for other values.
+   *
+   * @evidence contracts/common.md#principled-implementation The value is dispatched by type, negative numbers use a prefix minus as expressions do, and object keys that are not identifiers are quoted.
+   * @evidence contracts/common.md#clear-and-simple-design One function with one branch per kind.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The dispatch is general.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the mapping.
+   */
   export const generate = (value: any): ts.TypeNode =>
     typeof value === "boolean"
       ? generateBoolean(value)

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

@@ -7,17 +7,52 @@ import { StatementFactory } from "../factories/StatementFactory";
 import ts from "../internal/ts";
 import { INestiaMigrateConfig } from "../structures/INestiaMigrateConfig";
 import { FilePrinter } from "../utils/FilePrinter";
+import { RequestBody } from "../utils/RequestBody";
+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(
@@ -41,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,
@@ -110,9 +155,7 @@ export namespace NestiaMigrateApiFunctionProgrammer {
               factory.createTypeReferenceNode(
                 `${ctx.route.accessor.at(-1)!}.Body`,
               ),
-              (ctx.route.body.type === "application/json" ||
-                ctx.route.body.type === "text/plain") &&
-                ctx.route.operation().requestBody?.required === false
+              RequestBody.optional(ctx.route)
                 ? factory.createToken(SyntaxKind.QuestionToken)
                 : undefined,
             ),
@@ -208,9 +251,15 @@ export namespace NestiaMigrateApiFunctionProgrammer {
                     getArguments(ctx, false),
                   ),
                 ),
+                // the fetcher reads only 200, 201, and this status as success
                 factory.createPropertyAssignment(
                   "status",
-                  factory.createNull(),
+                  ((status) =>
+                    status === null
+                      ? factory.createNull()
+                      : factory.createNumericLiteral(status))(
+                    SuccessStatus.of(ctx.route),
+                  ),
                 ),
               ],
               true,