@nestia/migrate 14.0.0 → 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

@@ -2,6 +2,7 @@ import { SyntaxKind, factory } from "@ttsc/factory";
 import { IHttpMigrateRoute } from "@typia/interface";
 import { OpenApi } from "typia";
 
+import { NestiaMigrateControllerAnalyzer } from "../analyzers/NestiaMigrateControllerAnalyzer";
 import { ExpressionFactory } from "../factories/ExpressionFactory";
 import { IdentifierFactory } from "../factories/IdentifierFactory";
 import { LiteralFactory } from "../factories/LiteralFactory";
@@ -10,19 +11,55 @@ import ts from "../internal/ts";
 import { INestiaMigrateConfig } from "../structures/INestiaMigrateConfig";
 import { INestiaMigrateController } from "../structures/INestiaMigrateController";
 import { FilePrinter } from "../utils/FilePrinter";
+import { RequestBody } from "../utils/RequestBody";
 import { StringUtil } from "../utils/StringUtil";
+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({
@@ -121,7 +158,9 @@ export namespace NestiaMigrateNestMethodProgrammer {
       );
 
     // ROUTER
-    const localPath: string = ctx.route.emendedPath
+    const localPath: string = NestiaMigrateControllerAnalyzer.routePath(
+      ctx.route,
+    )
       .slice(ctx.controller.path.length)
       .split("/")
       .filter((str) => !!str.length)
@@ -139,35 +178,43 @@ export namespace NestiaMigrateNestMethodProgrammer {
             : undefined,
         ),
       );
+    // a vanilla NestJS method decorator, relative to the controller like the
+    // nestia ones: the document's full path would be joined onto the
+    // controller's again
+    const nest = (method: string) =>
+      factory.createDecorator(
+        factory.createCallExpression(
+          external("@nestjs/common", method),
+          [],
+          localPath.length
+            ? [factory.createStringLiteral(localPath)]
+            : undefined,
+        ),
+      );
     if (ctx.route.success?.["x-nestia-encrypted"])
       decorators.push(router("EncryptedRoute"));
     else if (ctx.route.success?.type === "text/plain")
-      decorators.push(
-        factory.createDecorator(
-          factory.createCallExpression(
-            external("@nestjs/common", StringUtil.capitalize(ctx.route.method)),
-            [],
-            [factory.createStringLiteral(ctx.route.path)],
-          ),
-        ),
-      );
+      decorators.push(nest(StringUtil.capitalize(ctx.route.method)));
     else if (ctx.route.success?.type === "application/x-www-form-urlencoded")
       decorators.push(router("TypedQuery"));
-    else if (ctx.route.method === "head")
+    else if (ctx.route.method === "head") decorators.push(nest("Head"));
+    else if (
+      ctx.route.success === null ||
+      ctx.route.success?.type === "application/json"
+    )
+      decorators.push(router("TypedRoute"));
+    // NestJS answers 201 for POST and 200 otherwise
+    const status: number | null = SuccessStatus.of(ctx.route);
+    if (status !== null && status !== SuccessStatus.nest(ctx.route))
       decorators.push(
         factory.createDecorator(
           factory.createCallExpression(
-            external("@nestjs/common", "Head"),
-            [],
-            [factory.createStringLiteral(ctx.route.path)],
+            external("@nestjs/common", "HttpCode"),
+            undefined,
+            [ExpressionFactory.number(status)],
           ),
         ),
       );
-    else if (
-      ctx.route.success === null ||
-      ctx.route.success?.type === "application/json"
-    )
-      decorators.push(router("TypedRoute"));
     for (const [key, value] of Object.entries(ctx.route.exceptions ?? {}))
       decorators.push(
         factory.createDecorator(
@@ -291,11 +338,7 @@ export namespace NestiaMigrateNestMethodProgrammer {
                 : [],
           })(ctx.components)(ctx.importer)({
             schema: ctx.route.body.schema,
-            required: !(
-              (ctx.route.body.type === "application/json" ||
-                ctx.route.body.type === "text/plain") &&
-              ctx.route.operation().requestBody?.required === false
-            ),
+            required: RequestBody.optional(ctx.route) === false,
             example: ctx.route.body.media().example,
             examples: ctx.route.body.media().examples,
           }),
@@ -380,8 +423,10 @@ export namespace NestiaMigrateNestMethodProgrammer {
             ),
           ]
         : []),
-      ...Object.entries(media.examples ?? {}).map(([key, value]) =>
-        factory.createDecorator(
+      ...Object.entries(media.examples ?? {}).flatMap(([key, example]) => {
+        const value: { value: unknown } | null = exampleValue(example);
+        if (value === null) return [];
+        return factory.createDecorator(
           factory.createCallExpression(
             IdentifierFactory.access(
               factory.createIdentifier(
@@ -394,9 +439,57 @@ export namespace NestiaMigrateNestMethodProgrammer {
               kind,
             ),
             [],
-            [factory.createStringLiteral(key), LiteralFactory.write(value)],
+            [
+              factory.createStringLiteral(key),
+              LiteralFactory.write(value.value),
+            ],
           ),
-        ),
-      ),
+        );
+      }),
     ];
 }
+
+/**
+ * The value a named example stands for, or `null` when it names none.
+ *
+ * OpenAPI names examples with Example Objects, whose `value` (or, since 3.2,
+ * `dataValue`) holds the value, and a `$ref` to one arrives resolved. Documents
+ * from earlier nestia versions held the values themselves, so an object is read
+ * as an Example Object only when it is one: it has one of the value fields, and
+ * every other key is an Example Object field or an extension. A raw value of
+ * exactly that shape is ambiguous and is read as an Example Object, as a
+ * conforming document means it. An Example Object that only points at its value
+ * (`externalValue`) or only serializes it (`serializedValue`) gives
+ * `SwaggerExample` nothing to hold.
+ */
+const exampleValue = (example: unknown): { value: unknown } | null => {
+  if (isExampleObject(example) === false) return { value: example };
+  const record = example as Record<string, unknown>;
+  if (Object.prototype.hasOwnProperty.call(record, "value"))
+    return { value: record.value };
+  if (Object.prototype.hasOwnProperty.call(record, "dataValue"))
+    return { value: record.dataValue };
+  return null;
+};
+
+const isExampleObject = (example: unknown): boolean =>
+  typeof example === "object" &&
+  example !== null &&
+  Array.isArray(example) === false &&
+  VALUE_KEYS.some((key) =>
+    Object.prototype.hasOwnProperty.call(example, key),
+  ) &&
+  Object.keys(example).every(
+    (key) =>
+      VALUE_KEYS.includes(key) ||
+      key === "summary" ||
+      key === "description" ||
+      key.startsWith("x-"),
+  );
+
+const VALUE_KEYS: string[] = [
+  "value",
+  "dataValue",
+  "serializedValue",
+  "externalValue",
+];

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;
@@ -123,12 +139,29 @@ export namespace NestiaMigrateSchemaProgrammer {
     writeNumeric({
       factory: () => [
         TypeFactory.keyword("number"),
-        props.importer.tag("Type", "int32"),
+        props.importer.tag("Type", integerType(props.schema)),
       ],
       importer: props.importer,
       schema: props.schema,
     });
 
+  /**
+   * The typia integer type admitting what the schema admits: its own `format`
+   * when it names one typia has, else `int64`, as an integer schema without a
+   * format admits any integer.
+   */
+  const integerType = (
+    schema: OpenApi.IJsonSchema.IInteger,
+  ): "int32" | "uint32" | "int64" | "uint64" => {
+    const format: unknown = (schema as { format?: unknown }).format;
+    return format === "int32" ||
+      format === "uint32" ||
+      format === "int64" ||
+      format === "uint64"
+      ? format
+      : "int64";
+  };
+
   const writeNumber = (props: {
     importer: NestiaMigrateImportProgrammer;
     schema: OpenApi.IJsonSchema.INumber;
@@ -147,19 +180,19 @@ export namespace NestiaMigrateSchemaProgrammer {
     const intersection: ts.TypeNode[] = props.factory();
     if (props.schema.default !== undefined)
       intersection.push(props.importer.tag("Default", props.schema.default));
+    // the emended schema holds each bound as a number, as OpenAPI 3.1 does;
+    // an OpenAPI 3.0 boolean `exclusiveMinimum` is converted into that form
     if (props.schema.minimum !== undefined)
+      intersection.push(props.importer.tag("Minimum", props.schema.minimum));
+    if (typeof props.schema.exclusiveMinimum === "number")
       intersection.push(
-        props.importer.tag(
-          props.schema.exclusiveMinimum ? "ExclusiveMinimum" : "Minimum",
-          props.schema.minimum,
-        ),
+        props.importer.tag("ExclusiveMinimum", props.schema.exclusiveMinimum),
       );
     if (props.schema.maximum !== undefined)
+      intersection.push(props.importer.tag("Maximum", props.schema.maximum));
+    if (typeof props.schema.exclusiveMaximum === "number")
       intersection.push(
-        props.importer.tag(
-          props.schema.exclusiveMaximum ? "ExclusiveMaximum" : "Maximum",
-          props.schema.maximum,
-        ),
+        props.importer.tag("ExclusiveMaximum", props.schema.exclusiveMaximum),
       );
     if (props.schema.multipleOf !== undefined)
       intersection.push(
@@ -192,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)
@@ -250,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
@@ -299,7 +333,8 @@ export namespace NestiaMigrateSchemaProgrammer {
           schema: props.schema.additionalProperties as OpenApi.IJsonSchema,
         }),
       ]);
-    return !!props.schema.properties?.length &&
+    // `properties` is a record, which has no length
+    return Object.keys(props.schema.properties ?? {}).length !== 0 &&
       typeof props.schema.additionalProperties === "object"
       ? factory.createIntersectionTypeNode([regular(), dynamic()])
       : typeof props.schema.additionalProperties === "object"

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;
 }