@nestia/migrate 14.0.0 → 14.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestia/migrate",
-  "version": "14.0.0",
+  "version": "14.0.2",
   "description": "Migration program from swagger to NestJS",
   "main": "lib/index.js",
   "bin": {
@@ -52,7 +52,7 @@
     "prettier": "^3.8.1",
     "prettier-plugin-jsdoc": "^1.8.0",
     "tstl": "^3.0.0",
-    "typia": "^15.0.0"
+    "typia": "15.0.0"
   },
   "files": [
     "lib",
@@ -67,10 +67,11 @@
     "access": "public"
   },
   "scripts": {
-    "build": "pnpm run bundle && rimraf lib && ttsc && tsc --emitDeclarationOnly && rolldown -c && node ../../deploy/verify-package-exports.cjs --esm",
+    "build": "pnpm run bundle && rimraf lib && ttsc && tsc --emitDeclarationOnly && rolldown -c",
     "bundle": "node src/executable/bundle.js",
     "dev": "rimraf lib && ttsc --watch",
-    "test": "node lib/test"
+    "test": "node lib/test",
+    "evidence": "evidence"
   },
   "types": "lib/index.d.ts",
   "module": "lib/index.mjs"

package/src/NestiaMigrateApplication.ts

@@ -9,6 +9,7 @@ import {
 } from "@typia/interface";
 import type { IValidation } from "@typia/interface";
 import { HttpMigration, OpenApiConverter } from "@typia/utils";
+import { TreeSet } from "tstl";
 
 import { NEST_TEMPLATE } from "./bundles/NEST_TEMPLATE";
 import { SDK_TEMPLATE } from "./bundles/SDK_TEMPLATE";
@@ -19,6 +20,32 @@ import { NestiaMigrateNestProgrammer } from "./programmers/NestiaMigrateNestProg
 import { INestiaMigrateConfig } from "./structures/INestiaMigrateConfig";
 import { INestiaMigrateContext } from "./structures/INestiaMigrateContext";
 
+/**
+ * Converts an OpenAPI document into a NestJS project or an SDK project, as a
+ * map from file path to file content.
+ *
+ * The constructor analyzes an emended OpenAPI document once; `assert` and
+ * `validate` upgrade a document of any supported version to that form first.
+ * `nest` and `sdk` then compose the files of the bundled template with the
+ * generated ones.
+ *
+ * The constructor analyzes the document once; generation walks templates and
+ * delegates per-route/schema emission, with the context builder’s accessor trie
+ * indexing strict prefixes.
+ *
+ * The instance shares its analyzed application between nest and sdk calls.
+ * Generation creates fresh context/accessor copies because its mode and config
+ * can differ.
+ *
+ * One instance retains its original document and analysis until callers release
+ * it; generated file maps are returned to callers rather than accumulated on
+ * the instance.
+ *
+ * @evidence contracts/common.md#principled-implementation The constructor analyzes the emended document into routes with `HttpMigration`, and the two generators start from the bundled template files, drop the paths the generators own (structures, functional API, controllers, feature tests), and add the generated files, so the result is the template with those trees replaced.
+ * @evidence contracts/common.md#clear-and-simple-design One class with two generators sharing one context builder; the accessor conflict escape and the package renaming are module-private functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Route analysis and the OpenAPI upgrade come from `@typia/utils`, and no document, path, or type name is special-cased; QUERY-method routes are left out because the SDK has no representation for them.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the class produces, when the document is analyzed, and how the two generators use the template.
+ */
 export class NestiaMigrateApplication {
   private readonly data_: IHttpMigrateApplication;
 
@@ -29,6 +56,18 @@ export class NestiaMigrateApplication {
     this.data_ = HttpMigration.application(document);
   }
 
+  /**
+   * Creates the application from a document of any supported OpenAPI or Swagger
+   * version, and throws when the document cannot be upgraded.
+   *
+   * Version conversion and route analysis scale with the document’s routes and
+   * schemas; this wrapper delegates each once.
+   *
+   * @evidence contracts/common.md#principled-implementation The document is upgraded by `OpenApiConverter.upgradeDocument`, which owns the version differences, so this function only wraps a successful result.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It does not repair or guess invalid documents.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the accepted versions and the throwing behavior.
+   */
   public static assert(
     document:
       | SwaggerV2.IDocument
@@ -42,6 +81,18 @@ export class NestiaMigrateApplication {
     );
   }
 
+  /**
+   * Creates the application, or returns the failure as an `IValidation` instead
+   * of throwing.
+   *
+   * Version conversion and route analysis scale with the document’s routes and
+   * schemas; validation delegates once and formats one caught failure.
+   *
+   * @evidence contracts/common.md#principled-implementation The upgrade runs inside a `try`, and an error becomes one validation error whose path is the input and whose value is the message, so a caller can report it.
+   * @evidence contracts/common.md#clear-and-simple-design The non-throwing twin of `assert`, sharing its constructor call.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The failure is reported, not hidden, and the message is the original one.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result shape.
+   */
   public static validate(
     document:
       | SwaggerV2.IDocument
@@ -77,10 +128,47 @@ export class NestiaMigrateApplication {
   /* -----------------------------------------------------------
     ACCESSORS
   ----------------------------------------------------------- */
+  /**
+   * Returns the analyzed application: the routes and the operations that could
+   * not be migrated.
+   *
+   * Returning the existing analysis reference uses constant work.
+   *
+   * The constructor’s analysis is returned directly to every caller; callers
+   * receive mutable shared state rather than an independently refreshed view.
+   *
+   * @evidence contracts/common.md#principled-implementation The analysis is done once in the constructor and returned by reference.
+   * @evidence contracts/common.md#clear-and-simple-design One accessor.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It exposes what the analysis produced.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is returned.
+   */
   public getData(): IHttpMigrateApplication {
     return this.data_;
   }
 
+  /**
+   * Generates a NestJS monorepo project from the document.
+   *
+   * The files are the template, the controllers, the module, the DTO
+   * structures, the functional API, and, when requested, the e2e tests. A
+   * package name replaces the placeholder in every file.
+   *
+   * Template filtering and renaming scale with template/output bytes;
+   * programmers traverse routes and schemas. Accessor conflict escape indexes R
+   * routes with at most D segments in a trie. Ordered terminal sets preserve
+   * first-route precedence with logarithmic updates, and each escape probes
+   * only the current D-segment path rather than scanning R routes. Trie state
+   * holds original/final prefixes only and is local to generation.
+   *
+   * The instance’s route analysis is reused. Each call recomputes
+   * mode/config-dependent output and copies accessors because conflict escaping
+   * mutates them; returned maps remain caller-owned.
+   *
+   * @evidence contracts/common.md#principled-implementation The context copies the routes and escapes accessors that would collide with a shorter accessor, the template entries of the generated trees are removed, the programmers write the replacements, and `keyword: false` rewrites the one template setting that selects keyword parameters.
+   * @evidence contracts/common.md#clear-and-simple-design One method that composes the generators; each generator owns its own files.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The template is the published starter, and the only textual edit of it is the documented keyword setting.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is generated and the package renaming.
+   */
   public nest(config: INestiaMigrateConfig): Record<string, string> {
     const context: INestiaMigrateContext = createContext(
       "nest",
@@ -111,6 +199,30 @@ export class NestiaMigrateApplication {
     return config.package ? renameSlug(config.package, files) : files;
   }
 
+  /**
+   * Generates an SDK project from the document.
+   *
+   * The files are the template, the DTO structures, the functional API, the
+   * start script, the swagger document in its emended form, and, when
+   * requested, the e2e tests. A package name replaces the placeholder in every
+   * file.
+   *
+   * Template filtering and renaming scale with template/output bytes;
+   * programmers traverse routes and schemas. Accessor conflict escape indexes R
+   * routes with at most D segments in a trie. Ordered terminal sets preserve
+   * first-route precedence with logarithmic updates, and each escape probes
+   * only the current D-segment path rather than scanning R routes. Trie state
+   * holds original/final prefixes only and is local to generation.
+   *
+   * The instance’s route analysis is reused; mode/config-dependent output is
+   * recomputed with fresh accessor copies, and returned maps remain
+   * caller-owned.
+   *
+   * @evidence contracts/common.md#principled-implementation The context is built as for `nest`, the template entries of the generated trees are removed, the programmers write the replacements, and the emended document the application was built from, which is the input after any upgrade, is written beside them as `swagger.json`.
+   * @evidence contracts/common.md#clear-and-simple-design One method that composes the generators, sharing the context builder with `nest`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The template is the published starter, and no document is special-cased.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what is generated and the package renaming.
+   */
   public sdk(config: INestiaMigrateConfig): Record<string, string> {
     const context: INestiaMigrateContext = createContext(
       "sdk",
@@ -161,21 +273,47 @@ const createContext = (
 const escapeConflictingAccessors = (
   routes: IHttpMigrateRoute[],
 ): IHttpMigrateRoute[] => {
-  for (const route of routes)
+  type Prefix = {
+    children: Map<string, Prefix>;
+    terminal: TreeSet<number>;
+  };
+  const create = (): Prefix => ({
+    children: new Map(),
+    terminal: new TreeSet(),
+  });
+  const root: Prefix = create();
+  const insert = (accessor: string[], index: number): Prefix => {
+    let node = root;
+    for (const segment of accessor) {
+      let child = node.children.get(segment);
+      if (child === undefined) {
+        child = create();
+        node.children.set(segment, child);
+      }
+      node = child;
+    }
+    node.terminal.insert(index);
+    return node;
+  };
+  const terminals = routes.map((route, index) => insert(route.accessor, index));
+  for (const [routeIndex, route] of routes.entries()) {
     while (true) {
-      const neighbor: IHttpMigrateRoute | undefined = routes.find(
-        (candidate) =>
-          candidate !== route &&
-          candidate.accessor.length < route.accessor.length &&
-          route.accessor
-            .slice(0, candidate.accessor.length)
-            .every((value, index) => value === candidate.accessor[index]),
-      );
-      if (neighbor === undefined) break;
-
-      const index: number = neighbor.accessor.length - 1;
-      route.accessor[index] = `_${route.accessor[index]}`;
+      let node = root;
+      let neighborIndex = Infinity;
+      for (let depth = 0; depth < route.accessor.length - 1; ++depth) {
+        const child = node.children.get(route.accessor[depth]!);
+        if (child === undefined) break;
+        node = child;
+        if (!node.terminal.empty())
+          neighborIndex = Math.min(neighborIndex, node.terminal.begin().value);
+      }
+      if (neighborIndex === Infinity) break;
+      const conflict = routes[neighborIndex]!.accessor.length - 1;
+      route.accessor[conflict] = `_${route.accessor[conflict]}`;
     }
+    terminals[routeIndex]!.terminal.erase(routeIndex);
+    insert(route.accessor, routeIndex);
+  }
   return routes;
 };
 

package/src/analyzers/NestiaMigrateControllerAnalyzer.ts

@@ -2,9 +2,47 @@ import { IHttpMigrateRoute } from "@typia/interface";
 
 import { INestiaMigrateController } from "../structures/INestiaMigrateController";
 import { MapUtil } from "../utils/MapUtil";
+import { PathTemplate } from "../utils/PathTemplate";
 import { StringUtil } from "../utils/StringUtil";
 
+/**
+ * Groups the routes of an application into NestJS controllers.
+ *
+ * Generated controller locations use portable slash spelling and directoryName
+ * applies Windows filename constraints on every host: invalid/control
+ * characters and trailing dots/spaces become underscores, and device names,
+ * including extension and superscript-digit forms, receive a prefix. Router
+ * paths retain their original URL meaning. Directory normalization is
+ * intentionally many-to-one; distinct controllers retain their own filenames.
+ * Host filesystem case policy is not inferred.
+ *
+ * @evidence contracts/common.md#principled-implementation Routes are grouped by the controller name from the operation, or by the capitalized accessor prefix, and each controller path is the longest path prefix shared by all of its routes, so one controller covers one resource path.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace with the grouping and the path formatting, and small private helpers for the shared-prefix computation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Names and paths derive from the document, with no route or controller name special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace NestiaMigrateControllerAnalyzer {
+  /**
+   * Returns the controllers of the routes, each with its name, its path, its
+   * source location, and its routes.
+   *
+   * The name is the `x-samchon-controller` extension of the operation when
+   * present, and otherwise the capitalized accessor prefix followed by
+   * `Controller`.
+   *
+   * Generated controller locations use portable slash spelling and
+   * directoryName applies Windows filename constraints on every host:
+   * invalid/control characters and trailing dots/spaces become underscores, and
+   * device names, including extension and superscript-digit forms, receive a
+   * prefix. Router paths retain their original URL meaning. Directory
+   * normalization is intentionally many-to-one; distinct controllers retain
+   * their own filenames. Host filesystem case policy is not inferred.
+   *
+   * @evidence contracts/common.md#principled-implementation Grouping uses a map keyed by controller name, and the common path prefix and the directory prefix are found by removing every segment after the first difference across the routes, so a controller path is a prefix of every route it owns.
+   * @evidence contracts/common.md#clear-and-simple-design One function with two phases: grouping, then prefix computation.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The extension name is part of the generated document contract; no other name is assumed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states how the name and the path are chosen.
+   */
   export const analyze = (
     routes: IHttpMigrateRoute[],
   ): INestiaMigrateController[] => {
@@ -27,9 +65,11 @@ export namespace NestiaMigrateControllerAnalyzer {
     const controllers: INestiaMigrateController[] = [...collection.values()];
     for (const col of controllers) {
       const splitPath = (r: IHttpMigrateRoute): string[] =>
-        r.emendedPath.split("/");
+        routePath(r).split("/");
       const splitLocation = (r: IHttpMigrateRoute): string[] =>
-        splitPath(r).filter((s) => s.length !== 0 && s[0] !== ":");
+        splitPath(r)
+          .filter((s) => s.length !== 0 && s[0] !== ":")
+          .map(directoryName);
 
       const minPath: string[] = splitPath(col.routes[0]!);
       const minLocation: string[] = splitLocation(col.routes[0]!);
@@ -42,8 +82,60 @@ export namespace NestiaMigrateControllerAnalyzer {
     }
     return controllers;
   };
+
+  /**
+   * The route's path as NestJS reads it: each path parameter under the key its
+   * handler reads with `@TypedParam()`. The document's name, such as `item-id`,
+   * is no path-to-regexp parameter name; it would read as `item` followed by
+   * the literal `-id`, and the handler's lookup would miss. Each parameter is
+   * found where the document's template writes it, beside literal text in its
+   * segment too (`/files/{id}.json`).
+   *
+   * A literal character the router reserves is escaped, so an AIP custom
+   * method's `/items:batchGet` stays a literal rather than a parameter
+   * `batchGet`, and `(` or `*` no syntax error.
+   *
+   * This operation emits router protocol spelling and does not select native
+   * filenames or filesystem identities.
+   *
+   * @evidence contracts/common.md#principled-implementation The path template is split into literal and parameter segments, and every character that path-to-regexp treats specially in a literal is escaped with a backslash, so a literal never changes the route's meaning.
+   * @evidence contracts/common.md#clear-and-simple-design One expression over the shared path segmenter.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The reserved set is the router's syntax and is applied to every literal.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the escaping and the parameter form.
+   */
+  export const routePath = (route: IHttpMigrateRoute): string =>
+    PathTemplate.segments(route)
+      .map((segment) =>
+        segment.type === "literal"
+          ? segment.value.replace(ROUTER_RESERVED, "\\$&")
+          : `:${segment.parameter.key}`,
+      )
+      .join("");
 }
 
+/**
+ * The characters path-to-regexp 8, Express 5's router, gives a meaning in a
+ * route: parameters, wildcards, optional groups, and its own escape.
+ */
+const ROUTER_RESERVED = /[\\:*?+!(){}[\]]/g;
+
+/**
+ * Maps a route segment to a portable directory component. Router escapes are
+ * removed, Windows-invalid characters and trailing dots/spaces become
+ * underscores, and reserved device names receive an underscore prefix. Distinct
+ * route segments may share a directory; controller files retain their
+ * independently assigned controller names.
+ */
+const directoryName = (segment: string): string => {
+  const name: string = segment
+    .replace(/\\(.)/g, "$1")
+    .replace(/[<>:"|?*\\\u0000-\u001f]/g, "_")
+    .replace(/[. ]+$/, (suffix) => "_".repeat(suffix.length));
+  return /^(?:CON|PRN|AUX|NUL|COM[1-9¹²³]|LPT[1-9¹²³])(?:\.|$)/i.test(name)
+    ? `_${name}`
+    : name || "_";
+};
+
 const getSplitIndex = (x: string[], y: string[]) => {
   const n: number = Math.min(x.length, y.length);
   for (let i: number = 0; i < n; ++i) if (x[i] !== y[i]) return i;

package/src/archivers/NestiaMigrateFileArchiver.ts

@@ -1,6 +1,40 @@
 import { VariadicSingleton } from "tstl";
 
+/**
+ * Writes a file map into a directory through injected file-system functions.
+ *
+ * Each path is the root, a `/` and the key's `/`-separated segments, a spelling
+ * the filesystem calls of every supported platform accept, and creation and
+ * writing are delegated to injected functions, so the caller's filesystem
+ * decides existence, case policy and permissions. Directories are created one
+ * segment at a time because the injected creator is not recursive. Remaining
+ * assumptions: keys are trusted generated names, since a `..` or absolute
+ * segment would leave the root, and on a case-insensitive volume two keys that
+ * differ only in case write to the same file.
+ *
+ * @evidence contracts/common.md#principled-implementation Directories are created one path prefix at a time, each once, through a memoized creator, and the files are then written in the order of the map; injecting the functions keeps the archiver independent of Node and of the browser.
+ * @evidence contracts/common.md#clear-and-simple-design One function with one memoized directory creator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It writes exactly the given files, and injection is the supported boundary for the platform.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace NestiaMigrateFileArchiver {
+  /**
+   * Writes every file of `files` below `root`, creating the directories on the
+   * way.
+   *
+   * A directory that cannot be created is not reported, because the creator is
+   * also called for a directory that already exists; the failure surfaces when
+   * the file is written.
+   *
+   * The memo of created directories is keyed by the spelled path, so on a
+   * case-insensitive volume a second spelling attempts the creation again and
+   * receives the already-exists error, which is the swallowed outcome.
+   *
+   * @evidence contracts/common.md#principled-implementation The root and each prefix of each file's directory are created once, in order, before the file is written, and a creation failure is deferred to the write that needs the directory, since the injected creator is not recursive and reports an existing directory as an error.
+   * @evidence contracts/common.md#clear-and-simple-design One function; the memoized creator makes a repeated directory a no-op.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The dropped creation error is a stated consequence of the non-recursive creator, and the write still fails loudly when the directory is missing.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the order of creation and the deferred error.
+   */
   export const archive = async (props: {
     mkdir: (path: string) => Promise<void>;
     writeFile: (path: string, content: string) => Promise<void>;

package/src/bundles/NEST_TEMPLATE.ts

@@ -49,6 +49,6 @@ export const NEST_TEMPLATE: Record<string, string> = {
   "packages/backend/test/webpack.ts": "import { DynamicExecutor } from \"@nestia/e2e\";\nimport cp from \"node:child_process\";\nimport { sleep_for } from \"tstl\";\n\nimport { MyConfiguration } from \"../src/MyConfiguration\";\nimport { MyGlobal } from \"../src/MyGlobal\";\nimport { TestAutomation } from \"./helpers/TestAutomation\";\nimport { TestAutomationStdio } from \"./helpers/TestAutomationStdio\";\n\nconst wait = async (): Promise<void> => {\n  while (true)\n    try {\n      await fetch(`http://localhost:${MyConfiguration.API_PORT()}/dsafdsafsd`);\n      return;\n    } catch (exp) {\n      await sleep_for(100);\n    }\n};\n\nconst main = async (): Promise<void> => {\n  MyGlobal.testing = true;\n\n  const report: DynamicExecutor.IReport = await TestAutomation.execute({\n    open: async () => {\n      const backend: cp.ChildProcess = cp.fork(\n        `${MyConfiguration.ROOT}/dist/server.js`,\n        {\n          cwd: `${MyConfiguration.ROOT}/dist`,\n        },\n      );\n      await wait();\n      return backend;\n    },\n    close: async (backend) => {\n      backend.kill();\n    },\n    options: await TestAutomationStdio.getOptions(),\n    onComplete: TestAutomationStdio.onComplete,\n  });\n  TestAutomationStdio.report(report);\n};\nmain().catch((exp: unknown) => {\n  console.log(exp);\n  process.exit(-1);\n});\n",
   "packages/backend/tsconfig.json": "{\n  \"extends\": \"../../config/tsconfig.json\",\n  \"compilerOptions\": {\n    \"outDir\": \"lib\",\n    \"rootDir\": \"src\",\n    \"experimentalDecorators\": true,\n    \"emitDecoratorMetadata\": true\n  },\n  \"include\": [\"src\"]\n}\n",
   "packages/backend/webpack.config.js": "const path = require(\"path\");\n\nconst CopyWebpackPlugin = require(\"copy-webpack-plugin\");\nconst WriteFilePlugin = require(\"write-file-webpack-plugin\");\nconst { IgnorePlugin } = require(\"webpack\");\n\nconst lazyImports = [\n  \"@modelcontextprotocol/sdk\",\n  \"@fastify/static\",\n  \"@fastify/view\",\n  \"@nestjs/microservices\",\n  \"@nestjs/websockets\",\n  \"class-transformer\",\n  \"class-validator\",\n];\n\n// @reference https://tech-blog.s-yoshiki.com/entry/297\nmodule.exports = {\n  // CUSTOMIZE HERE\n  entry: {\n    server: \"./lib/executable/server.js\",\n  },\n  output: {\n    path: path.join(__dirname, \"dist\"),\n    filename: \"[name].js\",\n  },\n  optimization: {\n    minimize: true,\n  },\n\n  // JUST KEEP THEM\n  mode: \"production\",\n  target: \"node\",\n  plugins: [\n    new CopyWebpackPlugin({\n      patterns: [\n        {\n          from: \".env\",\n          to: \"[name][ext]\",\n        },\n      ],\n    }),\n    new WriteFilePlugin(),\n    new IgnorePlugin({\n      checkResource: (resource) => {\n        if (lazyImports.some((modulo) => resource.startsWith(modulo))) {\n          try {\n            require.resolve(resource);\n          } catch (err) {\n            return true;\n          }\n        }\n        return false;\n      },\n    }),\n  ],\n};\n",
-  "pnpm-workspace.yaml": "packages:\n  - \"config\"\n  - \"packages/*\"\ncatalogs:\n  samchon:\n    \"@nestia/benchmark\": ^14.0.0\n    \"@nestia/core\": ^14.0.0\n    \"@nestia/e2e\": ^14.0.0\n    \"@nestia/fetcher\": ^14.0.0\n    \"@nestia/sdk\": ^14.0.0\n    nestia: ^14.0.0\n    tgrid: ^1.2.1\n    tstl: ^3.0.0\n    typia: ^15.0.0\n  rolldown:\n    rolldown: ^1.1.5\n  utils:\n    rimraf: ^6.1.3\n    uuid: ^13.0.0\n  typescript:\n    \"@ttsc/lint\": ^0.18.2\n    \"@ttsc/paths\": ^0.18.2\n    \"@ttsc/unplugin\": ^0.28.1\n    ttsc: ^0.28.1\n    typescript: ^7.0.2\n",
+  "pnpm-workspace.yaml": "packages:\n  - \"config\"\n  - \"packages/*\"\ncatalogs:\n  samchon:\n    \"@nestia/benchmark\": ^14.0.2\n    \"@nestia/core\": ^14.0.2\n    \"@nestia/e2e\": ^14.0.2\n    \"@nestia/fetcher\": ^14.0.2\n    \"@nestia/sdk\": ^14.0.2\n    nestia: ^14.0.2\n    tgrid: ^1.2.1\n    tstl: ^3.0.0\n    typia: 15.0.0\n  rolldown:\n    rolldown: ^1.1.5\n  utils:\n    rimraf: ^6.1.3\n    uuid: ^13.0.0\n  typescript:\n    \"@ttsc/lint\": ^0.18.2\n    \"@ttsc/paths\": ^0.18.2\n    \"@ttsc/unplugin\": ^0.28.1\n    ttsc: ^0.28.1\n    typescript: ^7.0.2\n",
   "typos.toml": "[default]\nlocale = 'en-us'\nextend-ignore-re = [\n  \"(?Rm)^.*(<!--|#|//)\\\\s*spellchecker:disable-line(-->|\\n)?$\",\n  \"(?s)(<!--|#|//)\\\\s*spellchecker:off\\\\s*(-->|\\n).*?(<!--|#|//)\\\\s*spellchecker:on\",\n]\n\n[default.extend-words]\nJeongho = \"Jeongho\"\nNam = \"Nam\"\ntypia = \"typia\"\n\n[files]\nextend-exclude = [\"*.json\"]"
 }

package/src/bundles/SDK_TEMPLATE.ts

@@ -5,7 +5,7 @@ export const SDK_TEMPLATE: Record<string, string> = {
   "LICENSE": "MIT License\n\nCopyright (c) 2024 Jeongho Nam\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
   "README.md": "# Software Development Kit\nThis is a SDK library generated by [`@nestia/migrate`](https://nestia.io/docs/migrate) or [`@nestia/editor`](https://nestia.io/docs/editor).\n\nWith this SDK library, you can easily and safely interact with backend server.\n\nJust import and call some API functions like gif image below:\n\n![nestia-sdk-demo](https://user-images.githubusercontent.com/13158709/215004990-368c589d-7101-404e-b81b-fbc936382f05.gif)\n\n> Left is server code, and right is client code utilizing the SDK\n\n\n\n\n## How to Test\n```bash\npnpm install\npnpm run start # run only \"test/start.ts\" file\npnpm run test # everything under the \"test/features\" directory\npnpm run test:simulate # \"test/features\" with mockup simulation mode\n```\n\nIf you run `pnpm run start` command, only [test/start.ts](test/start.ts) file would be executed.\n\nOtherwise you run `pnpm run test` command instead, run everything in the [test/features](test/features) directory.\n\nFor reference, the [test/features](test/features) directory and E2E test functions (for each API endpoints) would be automatically composed only when you've configured the \"E2E test function generation mode\" of the `@nestia/migrate` (or `@nestia/editor`).\n\n```bash\npnpm dlx @nestia/migrate\n? Migration mode (Use arrow keys):\n    NestJS\n  > SDK\n? Swagger file location: assets/input/clickhouse.json\n? Output directory path: assets/output/clickhouse-sdk-manual\n? Mokup Simulator: true\n? E2E Test Functions: true\n```\n\n\n\n\n## Deploy\n```bash\npnpm install\npnpm run deploy\n```\n\nJust run `pnpm run deploy` command, then your SDK library would be published.\n\nBy the way, the initial package name of this template repository is `@ORGANIZATION/PROJECT-api`. I think it would better to change the word to your own organization and project name. If you're utilizing `VsCode`, you can do it through `Edit > Replace in Files` (*Ctrl + Shift + H*) feature.\n\n-----------\n\n> ## What [`Nestia`](https://nestia.io) is:\n> ![Nestia Logo](https://nestia.io/logo.png)\n> \n> [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/nestia/blob/master/LICENSE)\n> [![npm version](https://img.shields.io/npm/v/@nestia/core.svg)](https://www.npmjs.com/package/@nestia/core)\n> [![Downloads](https://img.shields.io/npm/dm/@nestia/core.svg)](https://www.npmjs.com/package/@nestia/core)\n> [![Build Status](https://github.com/samchon/nestia/workflows/build/badge.svg)](https://github.com/samchon/nestia/actions?query=workflow%3Abuild)\n> [![Guide Documents](https://img.shields.io/badge/guide-documents-forestgreen)](https://nestia.io/docs/)\n> \n> Nestia is a set of helper libraries for NestJS, supporting below features:\n> \n>   - `@nestia/core`: Super-fast decorators\n>   - `@nestia/sdk`:\n>     - Swagger generator evolved than ever\n>     - SDK library generator for clients\n>     - Mockup Simulator for client applications\n>     - Automatic E2E test functions generator\n>   - `@nestia/migrate`: Migration from Swagger to NestJS\n>   - `@nestia/editor`: Online TypeScript Swagger Editor\n>   - `nestia`: Just CLI (command line interface) tool\n> \n>> **Note**\n>> \n>> - **Only one line** required, with pure TypeScript type\n>> - Enhance performance **30x** up\n>>   - Runtime validator is **20,000x faster** than `class-validator`\n>>   - JSON serialization is **200x faster** than `class-transformer`\n>> - Software Development Kit\n>>   - SDK is a collection of `fetch` functions with type definitions like [tRPC](https://> trpc.io/)\n>>   - Mockup simulator means embedded backend simulator in SDK\n>>     - similar with [msw](https://mswjs.io/), but fully automated\n",
   "hello.js": "function print(command, description) {\n  return console.log(`\\x1b[1m${command}\\x1b[2m: ${description}\\x1b[0m`);\n}\n\nconsole.log(\"-----------------------------------------\");\nconsole.log(\"\\x1b[7mGenerated by \\x1b[2m@nestia/editor\\x1b[0m\");\nconsole.log(\"\");\nconsole.log(\" - \\x1b[36mhttps://nestia.io/docs/editor\\x1b[0m\");\nconsole.log(\" - \\x1b[36mhttps://github.com/samchon/nestia\\x1b[0m\");\nconsole.log(\"-----------------------------------------\");\n\nprint(\"pnpm run start\", \"Run only test/start.ts\");\nprint(\"pnpm run test\", \"Run every test/features/**/*.ts files\");\nprint(\"pnpm run test:simulate\", \"Test with mockup simulator\");\n",
-  "package.json": "{\n  \"name\": \"@ORGANIZATION/PROJECT-api\",\n  \"version\": \"0.1.0\",\n  \"description\": \"SDK library generated by Nestia\",\n  \"main\": \"src/index.ts\",\n  \"exports\": {\n    \".\": \"./src/index.ts\",\n    \"./lib/*\": \"./src/*.ts\",\n    \"./package.json\": \"./package.json\"\n  },\n  \"publishConfig\": {\n    \"main\": \"lib/index.mjs\",\n    \"module\": \"lib/index.mjs\",\n    \"types\": \"lib/index.d.ts\",\n    \"exports\": {\n      \".\": {\n        \"types\": \"./lib/index.d.ts\",\n        \"import\": \"./lib/index.mjs\",\n        \"default\": \"./lib/index.js\"\n      },\n      \"./lib/*\": {\n        \"types\": \"./lib/*.d.ts\",\n        \"import\": \"./lib/*.mjs\",\n        \"default\": \"./lib/*.js\"\n      },\n      \"./package.json\": \"./package.json\"\n    }\n  },\n  \"scripts\": {\n    \"build\": \"rimraf lib && ttsc && rolldown -c\",\n    \"build:test\": \"rimraf bin && ttsc --project test/tsconfig.json\",\n    \"deploy\": \"pnpm run build && pnpm publish\",\n    \"dev\": \"pnpm run build:test --watch\",\n    \"hello\": \"node hello\",\n    \"start\": \"ttsx test/start.ts\",\n    \"swagger\": \"ttsx test/swagger.ts\",\n    \"test\": \"ttsx test/index.ts\",\n    \"test:simulate\": \"ttsx test/index.ts --simulate true\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/samchon/nestia\"\n  },\n  \"author\": \"Jeongho Nam\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/samchon/nestia/issues\"\n  },\n  \"homepage\": \"https://nestia.io\",\n  \"files\": [\n    \"lib\",\n    \"swagger.json\",\n    \"package.json\",\n    \"README.md\"\n  ],\n  \"dependencies\": {\n    \"@nestia/fetcher\": \"^14.0.0\",\n    \"tgrid\": \"^1.2.1\",\n    \"typia\": \"^15.0.0\"\n  },\n  \"devDependencies\": {\n    \"@nestia/e2e\": \"^14.0.0\",\n    \"@ttsc/unplugin\": \"^0.28.1\",\n    \"@types/express\": \"^4.17.21\",\n    \"@types/swagger-ui-express\": \"^4.1.6\",\n    \"chalk\": \"4.1.2\",\n    \"express\": \"^4.19.2\",\n    \"rimraf\": \"^5.0.5\",\n    \"rolldown\": \"^1.1.5\",\n    \"swagger-ui-express\": \"^5.0.0\",\n    \"tinyglobby\": \"^0.2.17\",\n    \"ttsc\": \"^0.28.1\",\n    \"typescript\": \"^7.0.2\",\n    \"@nestia/core\": \"^14.0.0\"\n  },\n  \"packageManager\": \"pnpm@10.19.0\"\n}",
+  "package.json": "{\n  \"name\": \"@ORGANIZATION/PROJECT-api\",\n  \"version\": \"0.1.0\",\n  \"description\": \"SDK library generated by Nestia\",\n  \"main\": \"src/index.ts\",\n  \"exports\": {\n    \".\": \"./src/index.ts\",\n    \"./lib/*\": \"./src/*.ts\",\n    \"./package.json\": \"./package.json\"\n  },\n  \"publishConfig\": {\n    \"main\": \"lib/index.mjs\",\n    \"module\": \"lib/index.mjs\",\n    \"types\": \"lib/index.d.ts\",\n    \"exports\": {\n      \".\": {\n        \"types\": \"./lib/index.d.ts\",\n        \"import\": \"./lib/index.mjs\",\n        \"default\": \"./lib/index.js\"\n      },\n      \"./lib/*\": {\n        \"types\": \"./lib/*.d.ts\",\n        \"import\": \"./lib/*.mjs\",\n        \"default\": \"./lib/*.js\"\n      },\n      \"./package.json\": \"./package.json\"\n    }\n  },\n  \"scripts\": {\n    \"build\": \"rimraf lib && ttsc && rolldown -c\",\n    \"build:test\": \"rimraf bin && ttsc --project test/tsconfig.json\",\n    \"deploy\": \"pnpm run build && pnpm publish\",\n    \"dev\": \"pnpm run build:test --watch\",\n    \"hello\": \"node hello\",\n    \"start\": \"ttsx test/start.ts\",\n    \"swagger\": \"ttsx test/swagger.ts\",\n    \"test\": \"ttsx test/index.ts\",\n    \"test:simulate\": \"ttsx test/index.ts --simulate true\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"https://github.com/samchon/nestia\"\n  },\n  \"author\": \"Jeongho Nam\",\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/samchon/nestia/issues\"\n  },\n  \"homepage\": \"https://nestia.io\",\n  \"files\": [\n    \"lib\",\n    \"swagger.json\",\n    \"package.json\",\n    \"README.md\"\n  ],\n  \"dependencies\": {\n    \"@nestia/fetcher\": \"^14.0.2\",\n    \"tgrid\": \"^1.2.1\",\n    \"typia\": \"15.0.0\"\n  },\n  \"devDependencies\": {\n    \"@nestia/e2e\": \"^14.0.2\",\n    \"@ttsc/unplugin\": \"^0.28.1\",\n    \"@types/express\": \"^4.17.21\",\n    \"@types/swagger-ui-express\": \"^4.1.6\",\n    \"chalk\": \"4.1.2\",\n    \"express\": \"^4.19.2\",\n    \"rimraf\": \"^5.0.5\",\n    \"rolldown\": \"^1.1.5\",\n    \"swagger-ui-express\": \"^5.0.0\",\n    \"tinyglobby\": \"^0.2.17\",\n    \"ttsc\": \"^0.28.1\",\n    \"typescript\": \"^7.0.2\",\n    \"@nestia/core\": \"^14.0.2\"\n  },\n  \"packageManager\": \"pnpm@10.19.0\"\n}",
   "rolldown.config.mjs": "import ttsc from \"@ttsc/unplugin/rolldown\";\nimport path from \"node:path\";\nimport { globSync } from \"tinyglobby\";\n\nexport default {\n  input: globSync(\"./src/**/*.ts\"),\n  external: (id) => !id.startsWith(\".\") && !path.isAbsolute(id),\n  output: {\n    dir: \"./lib\",\n    format: \"esm\",\n    sourcemap: true,\n    entryFileNames: \"[name].mjs\",\n    preserveModules: true,\n    preserveModulesRoot: \"src\",\n  },\n  plugins: [ttsc()],\n};\n",
   "src/HttpError.ts": "export { HttpError } from \"@nestia/fetcher\";\n",
   "src/IConnection.ts": "export type { IConnection } from \"@nestia/fetcher\";\n",

package/src/executable/NestiaMigrateCommander.ts

@@ -15,7 +15,43 @@ import { NestiaMigrateApplication } from "../NestiaMigrateApplication";
 import { NestiaMigrateFileArchiver } from "../archivers/NestiaMigrateFileArchiver";
 import { NestiaMigrateInquirer } from "./NestiaMigrateInquirer";
 
+/**
+ * The command-line entry of `@nestia/migrate`.
+ *
+ * The output path is resolved with `path.resolve` and its parent tested with
+ * `existsSync` and `statSync`, with backslashes converted to `/`, which Windows
+ * accepts. The input is fetched when it parses as an http or https URL, so a
+ * Windows path whose drive letter parses as a scheme is read from disk, and it
+ * is read as UTF-8 otherwise. Only files with a `.ts`, `.cts`, `.mts` or `.tsx`
+ * extension, tested case-sensitively, are formatted, and text is written
+ * without a byte order mark and with the line endings the generator and
+ * Prettier produce, which are not the platform's. A failure ends the process
+ * through `process.exit(-1)`, whose status the platform truncates to a non-zero
+ * value.
+ *
+ * @evidence contracts/common.md#principled-implementation The command reads the options, validates the output directory, reads the document from a file or an http(s) URL, converts it, reports the operations that could not be migrated, and writes the files, formatting only TypeScript files.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function, with formatting, halting, and URL detection as private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every failure ends with a message and a non-zero exit, and unformattable content is written unformatted.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace NestiaMigrateCommander {
+  /**
+   * Runs the command: reads the options and the document, generates the
+   * project, and writes it to the output directory.
+   *
+   * It stops with an error when the output directory exists, when its parent
+   * does not exist or is not a directory, when the input cannot be read or
+   * fetched, or when the document is invalid.
+   *
+   * Creation and writing use `fs.promises` through the injected archiver, so
+   * the volume decides case policy and permissions, and the checks that precede
+   * any write are the filesystem's own answers.
+   *
+   * @evidence contracts/common.md#principled-implementation The checks run before any file is written, the document is fetched only for an http or https URL, a failed HTTP status stops the command, and only files with a TypeScript extension are formatted, because Prettier's TypeScript parser would rewrite a dotfile line into code.
+   * @evidence contracts/common.md#clear-and-simple-design One asynchronous function whose phases are marked in comments, with the option parsing in `NestiaMigrateInquirer`.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The checks apply to every input, and a formatting failure keeps the original text.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the conditions under which it stops.
+   */
   export const main = async (): Promise<void> => {
     const resolve = (str: string | undefined) =>
       str ? path.resolve(str).split("\\").join("/") : undefined;
@@ -39,6 +75,10 @@ export namespace NestiaMigrateCommander {
       | OpenApiV3_2.IDocument = await (async () => {
       if (isUri(options.input)) {
         const response: Response = await fetch(options.input);
+        if (response.ok === false)
+          halt(
+            `Unable to fetch the input swagger.json: ${response.status} ${response.statusText}`,
+          );
         const content: string = await response.text();
         return JSON.parse(content);
       }
@@ -76,8 +116,14 @@ export namespace NestiaMigrateCommander {
         );
     await NestiaMigrateFileArchiver.archive({
       mkdir: fs.promises.mkdir,
+      // only TypeScript is formatted: prettier's TypeScript parser also
+      // accepts a `.gitignore` or `.env` line, and rewrites it into code
       writeFile: async (file, content) =>
-        fs.promises.writeFile(file, await beautify(content), "utf-8"),
+        fs.promises.writeFile(
+          file,
+          /\.[cm]?tsx?$/.test(file) ? await beautify(content) : content,
+          "utf-8",
+        ),
       root: options.output,
       files,
     });

package/src/executable/NestiaMigrateInquirer.ts

@@ -1,7 +1,25 @@
 import { program } from "commander";
 import { createPromptModule } from "inquirer";
 
+/**
+ * Reads the options of the command from flags, asking interactively for what is
+ * missing.
+ *
+ * @evidence contracts/common.md#principled-implementation Each option is taken from its flag when given, and asked with a prompt otherwise, so the same command runs non-interactively when every flag is present.
+ * @evidence contracts/common.md#clear-and-simple-design One function and the output type; the prompt helpers are local.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The prompts are the standard `inquirer` ones, and a flag always wins over a prompt.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ */
 export namespace NestiaMigrateInquirer {
+  /**
+   * The options of the command: the mode, the input and output locations, the
+   * flags, and the package name.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds the answers needed to run the migration, each as a value and not as an optional.
+   * @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 options.
+   */
   export interface IOutput {
     mode: "nest" | "sdk";
     input: string;
@@ -12,6 +30,17 @@ export namespace NestiaMigrateInquirer {
     package: string;
   }
 
+  /**
+   * Parses the flags and asks for the missing options.
+   *
+   * A boolean flag given without a value is `true`, and one given a value is
+   * true only for the text `true`.
+   *
+   * @evidence contracts/common.md#principled-implementation Commander parses the flags, the action asks a prompt for each undefined option, and boolean flags are normalized by one rule, so the result has every field set.
+   * @evidence contracts/common.md#clear-and-simple-design One function that wires the parser and the prompts around one action.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It asks only for what is missing.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the boolean flag rule.
+   */
   export const parse = async (): Promise<IOutput> => {
     // PREPARE ASSETS
     program.option("--mode [nest/sdk]", "migration mode");
@@ -74,32 +103,18 @@ export namespace NestiaMigrateInquirer {
       partial.input ??= await input("input")("Swagger file location");
       partial.output ??= await input("output")("Response directory path");
       partial.package ??= await input("package")("Package name");
-      partial.keyword ??=
-        (await select("keyword")("Keyword parameter mode")([
-          "true",
-          "false",
-        ])) === "true";
-
-      if (partial.keyword)
-        partial.keyword = (partial.keyword as any) === "true";
-      else
-        partial.keyword =
-          (await select("keyword")("Keyword parameter mode")([
-            "true",
-            "false",
-          ])) === "true";
-      if (partial.simulate)
-        partial.simulate = (partial.simulate as any) === "true";
-      else
-        partial.simulate =
-          (await select("simulate")("Mokup Simulator")(["true", "false"])) ===
-          "true";
-
-      if (partial.e2e) partial.e2e = (partial.e2e as any) === "true";
-      else
-        partial.e2e =
-          (await select("e2e")("Generate E2E tests")(["true", "false"])) ===
-          "true";
+      // a flag given alone is `true`, and one given a value is its text
+      const flag = (value: unknown): boolean | undefined =>
+        value === undefined ? undefined : value === true || value === "true";
+      const ask = async (name: string, message: string): Promise<boolean> =>
+        (await select(name)(message)(["true", "false"])) === "true";
+      partial.keyword =
+        flag(partial.keyword) ??
+        (await ask("keyword", "Keyword parameter mode"));
+      partial.simulate =
+        flag(partial.simulate) ?? (await ask("simulate", "Mokup Simulator"));
+      partial.e2e =
+        flag(partial.e2e) ?? (await ask("e2e", "Generate E2E tests"));
       return partial as IOutput;
     });
   };