@nestia/sdk 12.0.0-dev.20260601.1 → 12.0.0-dev.20260619.1

package/src/executable/internal/NestiaConfigLoader.ts

@@ -1,446 +1,451 @@
-import { doNotThrowTransformError } from "@nestia/core";
-import fs from "fs";
-import path from "path";
-import { pathToFileURL } from "url";
-
-import { INestiaConfig } from "../../INestiaConfig";
-import { EmittedJavaScriptPatcher } from "../../utils/EmittedJavaScriptPatcher";
-import { TsConfigReader } from "../../utils/TsConfigReader";
-import { TtscExecutor } from "../../utils/TtscExecutor";
-
-export namespace NestiaConfigLoader {
-  export interface ICompilerOptions {
-    raw: {
-      compilerOptions?: Record<string, any>;
-    };
-  }
-
-  export const compilerOptions = async (
-    project: string,
-  ): Promise<ICompilerOptions> => {
-    const configFileName = findConfigFile(process.cwd(), project);
-    if (!configFileName) throw new Error(`unable to find "${project}" file.`);
-    const tsconfig = await TsConfigReader.read(configFileName);
-    return {
-      raw: {
-        compilerOptions:
-          typeof tsconfig?.compilerOptions === "object"
-            ? (tsconfig.compilerOptions as Record<string, any>)
-            : {},
-      },
-    };
-  };
-
-  export const configurations = async (
-    file: string,
-    compilerOptions: Record<string, any>,
-  ): Promise<INestiaConfig[]> => {
-    if (fs.existsSync(path.resolve(file)) === false)
-      throw new Error(`Unable to find "${file}" file.`);
-
-    doNotThrowTransformError(false);
-
-    if (compilerOptions.plugins !== undefined)
-      assertPlugins(file, compilerOptions.plugins);
-
-    const configFile: string = await materializeConfiguration({
-      file,
-      compilerOptions,
-    });
-    const loaded: unknown = await loadMaterializedModule(configFile);
-    const instance: INestiaConfig | INestiaConfig[] = extractConfiguration(
-      file,
-      loaded,
-    );
-    const configurations: INestiaConfig[] = Array.isArray(instance)
-      ? instance
-      : [instance];
-
-    return assertConfigurations(file, configurations);
-  };
-
-  const MATERIALIZED_ROOTS: Set<string> = new Set();
-  let CLEANUP_REGISTERED: boolean = false;
-
-  const materializeConfiguration = async (props: {
-    file: string;
-    compilerOptions: Record<string, any>;
-  }): Promise<string> => {
-    const configFile: string = path.resolve(props.file);
-    const project: string = process.env.NESTIA_PROJECT ?? "tsconfig.json";
-    const projectFile: string | undefined = findConfigFile(
-      process.cwd(),
-      project,
-    );
-    if (projectFile === undefined)
-      throw new Error(`unable to find "${project}" file.`);
-
-    const projectRoot: string = path.dirname(path.resolve(projectFile));
-    const wrapperRoot: string = fs.mkdtempSync(
-      path.join(ensureMaterializedRoot(projectRoot), "tsconfig-"),
-    );
-    const outputRoot: string = fs.mkdtempSync(
-      path.join(ensureMaterializedRoot(projectRoot), "run-"),
-    );
-    const wrapperFile: string = path.join(wrapperRoot, "tsconfig.json");
-    const wrapperConfig = {
-      extends: projectFile,
-      compilerOptions: {
-        noEmit: false,
-        noUnusedLocals: false,
-        noUnusedParameters: false,
-        ...nodeAmbientCompilerOptions(projectRoot, props.compilerOptions),
-        outDir: outputRoot,
-        plugins: materializePlugins(props.compilerOptions.plugins),
-        rootDir: projectRoot,
-      },
-      include: [configFile],
-      exclude: [path.join(projectRoot, "src", "test", "**", "*")],
-    };
-    fs.writeFileSync(
-      wrapperFile,
-      JSON.stringify(wrapperConfig, null, 2),
-      "utf8",
-    );
-
-    try {
-      TtscExecutor.run({
-        cwd: projectRoot,
-        env: sdkTransformEnv(),
-        project: wrapperFile,
-      });
-    } catch (error) {
-      const stderr: string = readChildOutput(error, "stderr");
-      const stdout: string = readChildOutput(error, "stdout");
-      const detail: string = stderr || stdout;
-      const cause: Error =
-        error instanceof Error ? error : new Error(String(error));
-      const status: number | string | undefined =
-        (cause as { status?: number }).status ??
-        (cause as NodeJS.ErrnoException).code;
-      throw new Error(
-        detail
-          ? `failed to compile "${props.file}" through ttsc:\n${detail}`
-          : `failed to compile "${props.file}" through ttsc (exit code ${status ?? "unknown"}). Run \`npx ttsc -p ${projectFile}\` to see the underlying diagnostics.`,
-        { cause },
-      );
-    } finally {
-      fs.rmSync(wrapperRoot, { force: true, recursive: true });
-    }
-    await EmittedJavaScriptPatcher.importMetaUrl(outputRoot);
-
-    const configKey: string = emittedJavaScriptKey(projectRoot, configFile);
-    const next: string = path.join(outputRoot, configKey);
-    if (fs.existsSync(next) === false)
-      throw new Error(
-        `failed to materialize "${props.file}" through ttsc native transform.`,
-      );
-    return next;
-  };
-
-  const ensureMaterializedRoot = (projectRoot: string): string => {
-    const root: string = path.join(
-      projectRoot,
-      "node_modules",
-      ".nestia",
-      "config-loader",
-    );
-    fs.mkdirSync(root, { recursive: true });
-    MATERIALIZED_ROOTS.add(root);
-    if (CLEANUP_REGISTERED === false) {
-      CLEANUP_REGISTERED = true;
-      const sweep = (): void => {
-        for (const location of MATERIALIZED_ROOTS)
-          fs.rmSync(location, { force: true, recursive: true });
-      };
-      process.once("exit", sweep);
-      // process.once("exit", …) does not fire on SIGINT/SIGTERM. Without
-      // these handlers a Ctrl-C during codegen leaves `run-*` and
-      // `tsconfig-*` mkdtempSync directories behind under
-      // node_modules/.nestia/config-loader/ until a subsequent clean exit.
-      // The module-level CLEANUP_REGISTERED flag above guards against
-      // re-entrancy within this module; we deliberately do NOT gate on
-      // `process.listenerCount(signal) > 0` because the parallel sweep in
-      // `ConfigAnalyzer.ensureRuntimeCleanup` (or any user-app SIGINT
-      // handler) could register first, and that gate would skip our
-      // registration — leaving MATERIALIZED_ROOTS unswept on Ctrl-C.
-      // Windows note: `process.kill(pid, "SIGINT")` calls TerminateProcess
-      // rather than re-raising; whichever module registers FIRST runs its
-      // sweep, the second is skipped, RUNTIME/MATERIALIZED cleanup is
-      // best-effort on Windows. SIGHUP is a no-op for most common code
-      // paths on Windows (Node fires it on console-close and exits within
-      // seconds).
-      const onSignal = (signal: NodeJS.Signals): void => {
-        sweep();
-        process.kill(process.pid, signal);
-      };
-      for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
-        process.once(signal, onSignal);
-      }
-    }
-    return root;
-  };
-
-  const emittedJavaScriptKey = (projectRoot: string, file: string): string => {
-    const relative: string = path.relative(projectRoot, file);
-    const extension: string = path.extname(relative).toLowerCase();
-    const emitted: string =
-      extension === ".mts" ? ".mjs" : extension === ".cts" ? ".cjs" : ".js";
-    return path
-      .join(
-        path.dirname(relative),
-        `${path.basename(relative, extension)}${emitted}`,
-      )
-      .split(path.sep)
-      .join(path.posix.sep);
-  };
-
-  const nodeAmbientCompilerOptions = (
-    projectRoot: string,
-    compilerOptions: Record<string, any>,
-  ): { typeRoots?: string[]; types: string[] } => {
-    const typeRoots: string[] = uniqueStrings([
-      ...asStringArray(compilerOptions.typeRoots),
-      ...resolveNodeTypeRoots(projectRoot),
-    ]);
-    const types: string[] = uniqueStrings([
-      "node",
-      ...asStringArray(compilerOptions.types).filter((value) => value !== "*"),
-    ]);
-    return {
-      ...(typeRoots.length !== 0 ? { typeRoots } : {}),
-      types,
-    };
-  };
-
-  const resolveNodeTypeRoots = (projectRoot: string): string[] => {
-    const roots: string[] = [];
-    for (const base of [projectRoot, process.cwd(), __dirname])
-      try {
-        const location: string = require.resolve("@types/node/package.json", {
-          paths: [base],
-        });
-        roots.push(path.dirname(path.dirname(location)));
-      } catch {
-        continue;
-      }
-    return roots;
-  };
-
-  const asStringArray = (input: unknown): string[] =>
-    Array.isArray(input)
-      ? input.filter((elem): elem is string => typeof elem === "string")
-      : [];
-
-  const uniqueStrings = (input: string[]): string[] => [...new Set(input)];
-
-  type MaterializePlugin = Record<string, unknown> & { transform?: unknown };
-
-  const sdkTransformEnv = (): NodeJS.ProcessEnv =>
-    process.env.NESTIA_SDK_TRANSFORM === undefined
-      ? { NESTIA_SDK_TRANSFORM: "1" }
-      : {};
-
-  const materializePlugins = (input: unknown): MaterializePlugin[] => {
-    const plugins: MaterializePlugin[] = Array.isArray(input)
-      ? input
-          .filter((p) => typeof p === "object" && p !== null)
-          .map((p) => ({ ...(p as MaterializePlugin) }))
-      : [];
-    const typia: MaterializePlugin | undefined = plugins.find((p) =>
-      isTransform(p, "typia"),
-    );
-    const core: MaterializePlugin | undefined = plugins.find((p) =>
-      isTransform(p, "@nestia/core"),
-    );
-    return [
-      {
-        ...(typia ?? {}),
-        transform: "typia/lib/transform",
-        enabled: false,
-      },
-      normalizePlugin({
-        ...(core ?? {}),
-        transform: "@nestia/core/native/transform.cjs",
-      }),
-    ];
-  };
-
-  const normalizePlugin = (plugin: MaterializePlugin): MaterializePlugin => {
-    const output: MaterializePlugin = { ...plugin };
-    if (output.enabled === false) delete output.enabled;
-    return output;
-  };
-
-  const isTransform = (plugin: MaterializePlugin, name: string): boolean =>
-    typeof plugin.transform === "string" && plugin.transform.includes(name);
-
-  const findConfigFile = (cwd: string, project: string): string | undefined => {
-    const candidate: string = path.isAbsolute(project)
-      ? project
-      : path.resolve(cwd, project);
-    if (fs.existsSync(candidate)) return candidate;
-    if (path.isAbsolute(project) || project.includes(path.sep))
-      return undefined;
-
-    let current: string = path.resolve(cwd);
-    while (true) {
-      const next: string = path.join(current, project);
-      if (fs.existsSync(next)) return next;
-      const parent: string = path.dirname(current);
-      if (parent === current) return undefined;
-      current = parent;
-    }
-  };
-
-  const extractConfiguration = (
-    file: string,
-    loaded: unknown,
-  ): INestiaConfig | INestiaConfig[] => {
-    const candidates: unknown[] = [];
-    const collect = (value: unknown): void => {
-      if (isObject(value)) {
-        candidates.push(value.default);
-        candidates.push(value.NESTIA_CONFIG);
-        if (isObject(value.default)) {
-          candidates.push(value.default.default);
-          candidates.push(value.default.NESTIA_CONFIG);
-        }
-      }
-      candidates.push(value);
-    };
-    collect(loaded);
-    const matched: unknown = candidates.find(
-      (value) =>
-        Array.isArray(value) ||
-        (isObject(value) && Object.hasOwn(value, "input")),
-    );
-    if (matched === undefined)
-      throw new Error(
-        `invalid "${file}" data: configuration must be exported.`,
-      );
-    return matched as INestiaConfig | INestiaConfig[];
-  };
-
-  const loadMaterializedModule = async (file: string): Promise<unknown> => {
-    if (file.endsWith(".mjs")) {
-      const dynamicImport = new Function(
-        "specifier",
-        "return import(specifier)",
-      ) as (specifier: string) => Promise<unknown>;
-      return dynamicImport(pathToFileURL(file).href);
-    }
-    return require(file);
-  };
-
-  const assertPlugins = (
-    file: string,
-    input: unknown,
-  ): Array<Record<string, any>> => {
-    if (
-      Array.isArray(input) &&
-      input.every((elem) => typeof elem === "object" && elem !== null)
-    )
-      return input as Array<Record<string, any>>;
-    throw new Error(
-      `invalid "${file}" data: compilerOptions.plugins must be an array.`,
-    );
-  };
-
-  const assertConfigurations = (
-    file: string,
-    input: unknown[],
-  ): INestiaConfig[] => {
-    input.forEach((config, index) => assertConfig(file, config, index));
-    return input as INestiaConfig[];
-  };
-
-  const assertConfig = (file: string, input: unknown, index: number): void => {
-    if (isObject(input) === false)
-      throw new Error(
-        `invalid "${file}" data: configuration #${index} must be an object.`,
-      );
-    const config: INestiaConfig = input as unknown as INestiaConfig;
-    if (isInput(config.input) === false)
-      throw new Error(
-        `invalid "${file}" data: configuration #${index}.input is invalid.`,
-      );
-    for (const [key, value] of [
-      ["output", config.output],
-      ["distribute", config.distribute],
-      ["e2e", config.e2e],
-    ] as const)
-      if (value !== undefined && typeof value !== "string")
-        throw new Error(
-          `invalid "${file}" data: configuration #${index}.${key} must be a string.`,
-        );
-    for (const [key, value] of [
-      ["keyword", config.keyword],
-      ["simulate", config.simulate],
-      ["propagate", config.propagate],
-      ["clone", config.clone],
-      ["primitive", config.primitive],
-      ["assert", config.assert],
-      ["json", config.json],
-    ] as const)
-      if (value !== undefined && typeof value !== "boolean")
-        throw new Error(
-          `invalid "${file}" data: configuration #${index}.${key} must be a boolean.`,
-        );
-    if (config.swagger !== undefined && isSwagger(config.swagger) === false)
-      throw new Error(
-        `invalid "${file}" data: configuration #${index}.swagger is invalid.`,
-      );
-  };
-
-  const isInput = (input: unknown): input is INestiaConfig["input"] => {
-    if (
-      typeof input === "string" ||
-      typeof input === "function" ||
-      isStringArray(input)
-    )
-      return true;
-    if (isObject(input) === false) return false;
-    return (
-      isStringArray(input.include) &&
-      (input.exclude === undefined || isStringArray(input.exclude))
-    );
-  };
-
-  const isSwagger = (input: unknown): input is INestiaConfig.ISwaggerConfig => {
-    if (isObject(input) === false) return false;
-    return (
-      typeof input.output === "string" &&
-      (input.openapi === undefined ||
-        ["2.0", "3.0", "3.1", "3.2"].includes(input.openapi as string)) &&
-      (input.beautify === undefined ||
-        typeof input.beautify === "boolean" ||
-        typeof input.beautify === "number") &&
-      (input.additional === undefined ||
-        typeof input.additional === "boolean") &&
-      (input.decompose === undefined || typeof input.decompose === "boolean") &&
-      (input.operationId === undefined ||
-        typeof input.operationId === "function")
-    );
-  };
-
-  const isObject = (input: unknown): input is Record<string, unknown> =>
-    typeof input === "object" &&
-    input !== null &&
-    Array.isArray(input) === false;
-
-  const isStringArray = (input: unknown): input is string[] =>
-    Array.isArray(input) && input.every((elem) => typeof elem === "string");
-
-  const readChildOutput = (
-    error: unknown,
-    key: "stderr" | "stdout",
-  ): string => {
-    if (!error || typeof error !== "object" || !(key in error)) return "";
-    const value = (error as Record<string, unknown>)[key];
-    if (value === null || value === undefined) return "";
-    if (typeof value === "string") return value.trim();
-    if (Buffer.isBuffer(value)) return value.toString("utf8").trim();
-    return "";
-  };
-}
+import { doNotThrowTransformError } from "@nestia/core";
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import { EmittedJavaScriptPatcher } from "../../utils/EmittedJavaScriptPatcher";
+import { TsConfigReader } from "../../utils/TsConfigReader";
+import { TtscExecutor } from "../../utils/TtscExecutor";
+
+export namespace NestiaConfigLoader {
+  export interface ICompilerOptions {
+    raw: {
+      compilerOptions?: Record<string, any>;
+    };
+  }
+
+  export const compilerOptions = async (
+    project: string,
+  ): Promise<ICompilerOptions> => {
+    const configFileName = findConfigFile(process.cwd(), project);
+    if (!configFileName) throw new Error(`unable to find "${project}" file.`);
+    const tsconfig = await TsConfigReader.read(configFileName);
+    return {
+      raw: {
+        compilerOptions:
+          typeof tsconfig?.compilerOptions === "object"
+            ? (tsconfig.compilerOptions as Record<string, any>)
+            : {},
+      },
+    };
+  };
+
+  export const configurations = async (
+    file: string,
+    compilerOptions: Record<string, any>,
+  ): Promise<INestiaConfig[]> => {
+    if (fs.existsSync(path.resolve(file)) === false)
+      throw new Error(`Unable to find "${file}" file.`);
+
+    doNotThrowTransformError(false);
+
+    if (compilerOptions.plugins !== undefined)
+      assertPlugins(file, compilerOptions.plugins);
+
+    const configFile: string = await materializeConfiguration({
+      file,
+      compilerOptions,
+    });
+    const loaded: unknown = await loadMaterializedModule(configFile);
+    const instance: INestiaConfig | INestiaConfig[] = extractConfiguration(
+      file,
+      loaded,
+    );
+    const configurations: INestiaConfig[] = Array.isArray(instance)
+      ? instance
+      : [instance];
+
+    return assertConfigurations(file, configurations);
+  };
+
+  const MATERIALIZED_ROOTS: Set<string> = new Set();
+  let CLEANUP_REGISTERED: boolean = false;
+
+  const materializeConfiguration = async (props: {
+    file: string;
+    compilerOptions: Record<string, any>;
+  }): Promise<string> => {
+    const configFile: string = path.resolve(props.file);
+    const project: string = process.env.NESTIA_PROJECT ?? "tsconfig.json";
+    const projectFile: string | undefined = findConfigFile(
+      process.cwd(),
+      project,
+    );
+    if (projectFile === undefined)
+      throw new Error(`unable to find "${project}" file.`);
+
+    const projectRoot: string = path.dirname(path.resolve(projectFile));
+    const wrapperRoot: string = fs.mkdtempSync(
+      path.join(ensureMaterializedRoot(projectRoot), "tsconfig-"),
+    );
+    const outputRoot: string = fs.mkdtempSync(
+      path.join(ensureMaterializedRoot(projectRoot), "run-"),
+    );
+    const wrapperFile: string = path.join(wrapperRoot, "tsconfig.json");
+    const wrapperConfig = {
+      extends: projectFile,
+      compilerOptions: {
+        noEmit: false,
+        noUnusedLocals: false,
+        noUnusedParameters: false,
+        ...nodeAmbientCompilerOptions(projectRoot, props.compilerOptions),
+        // The wrapper compiles the config file only to require() its JS; .d.ts
+        // is never read, and tsgo's declaration emitter can nil-panic on a
+        // config that calls into Nest. Force it off regardless of the project.
+        declaration: false,
+        declarationMap: false,
+        outDir: outputRoot,
+        plugins: materializePlugins(props.compilerOptions.plugins),
+        rootDir: projectRoot,
+      },
+      include: [configFile],
+      exclude: [path.join(projectRoot, "src", "test", "**", "*")],
+    };
+    fs.writeFileSync(
+      wrapperFile,
+      JSON.stringify(wrapperConfig, null, 2),
+      "utf8",
+    );
+
+    try {
+      TtscExecutor.run({
+        cwd: projectRoot,
+        env: sdkTransformEnv(),
+        project: wrapperFile,
+      });
+    } catch (error) {
+      const stderr: string = readChildOutput(error, "stderr");
+      const stdout: string = readChildOutput(error, "stdout");
+      const detail: string = stderr || stdout;
+      const cause: Error =
+        error instanceof Error ? error : new Error(String(error));
+      const status: number | string | undefined =
+        (cause as { status?: number }).status ??
+        (cause as NodeJS.ErrnoException).code;
+      throw new Error(
+        detail
+          ? `failed to compile "${props.file}" through ttsc:\n${detail}`
+          : `failed to compile "${props.file}" through ttsc (exit code ${status ?? "unknown"}). Run \`npx ttsc -p ${projectFile}\` to see the underlying diagnostics.`,
+        { cause },
+      );
+    } finally {
+      fs.rmSync(wrapperRoot, { force: true, recursive: true });
+    }
+    await EmittedJavaScriptPatcher.importMetaUrl(outputRoot);
+
+    const configKey: string = emittedJavaScriptKey(projectRoot, configFile);
+    const next: string = path.join(outputRoot, configKey);
+    if (fs.existsSync(next) === false)
+      throw new Error(
+        `failed to materialize "${props.file}" through ttsc native transform.`,
+      );
+    return next;
+  };
+
+  const ensureMaterializedRoot = (projectRoot: string): string => {
+    const root: string = path.join(
+      projectRoot,
+      "node_modules",
+      ".nestia",
+      "config-loader",
+    );
+    fs.mkdirSync(root, { recursive: true });
+    MATERIALIZED_ROOTS.add(root);
+    if (CLEANUP_REGISTERED === false) {
+      CLEANUP_REGISTERED = true;
+      const sweep = (): void => {
+        for (const location of MATERIALIZED_ROOTS)
+          fs.rmSync(location, { force: true, recursive: true });
+      };
+      process.once("exit", sweep);
+      // process.once("exit", …) does not fire on SIGINT/SIGTERM. Without
+      // these handlers a Ctrl-C during codegen leaves `run-*` and
+      // `tsconfig-*` mkdtempSync directories behind under
+      // node_modules/.nestia/config-loader/ until a subsequent clean exit.
+      // The module-level CLEANUP_REGISTERED flag above guards against
+      // re-entrancy within this module; we deliberately do NOT gate on
+      // `process.listenerCount(signal) > 0` because the parallel sweep in
+      // `ConfigAnalyzer.ensureRuntimeCleanup` (or any user-app SIGINT
+      // handler) could register first, and that gate would skip our
+      // registration — leaving MATERIALIZED_ROOTS unswept on Ctrl-C.
+      // Windows note: `process.kill(pid, "SIGINT")` calls TerminateProcess
+      // rather than re-raising; whichever module registers FIRST runs its
+      // sweep, the second is skipped, RUNTIME/MATERIALIZED cleanup is
+      // best-effort on Windows. SIGHUP is a no-op for most common code
+      // paths on Windows (Node fires it on console-close and exits within
+      // seconds).
+      const onSignal = (signal: NodeJS.Signals): void => {
+        sweep();
+        process.kill(process.pid, signal);
+      };
+      for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+        process.once(signal, onSignal);
+      }
+    }
+    return root;
+  };
+
+  const emittedJavaScriptKey = (projectRoot: string, file: string): string => {
+    const relative: string = path.relative(projectRoot, file);
+    const extension: string = path.extname(relative).toLowerCase();
+    const emitted: string =
+      extension === ".mts" ? ".mjs" : extension === ".cts" ? ".cjs" : ".js";
+    return path
+      .join(
+        path.dirname(relative),
+        `${path.basename(relative, extension)}${emitted}`,
+      )
+      .split(path.sep)
+      .join(path.posix.sep);
+  };
+
+  const nodeAmbientCompilerOptions = (
+    projectRoot: string,
+    compilerOptions: Record<string, any>,
+  ): { typeRoots?: string[]; types: string[] } => {
+    const typeRoots: string[] = uniqueStrings([
+      ...asStringArray(compilerOptions.typeRoots),
+      ...resolveNodeTypeRoots(projectRoot),
+    ]);
+    const types: string[] = uniqueStrings([
+      "node",
+      ...asStringArray(compilerOptions.types).filter((value) => value !== "*"),
+    ]);
+    return {
+      ...(typeRoots.length !== 0 ? { typeRoots } : {}),
+      types,
+    };
+  };
+
+  const resolveNodeTypeRoots = (projectRoot: string): string[] => {
+    const roots: string[] = [];
+    for (const base of [projectRoot, process.cwd(), __dirname])
+      try {
+        const location: string = require.resolve("@types/node/package.json", {
+          paths: [base],
+        });
+        roots.push(path.dirname(path.dirname(location)));
+      } catch {
+        continue;
+      }
+    return roots;
+  };
+
+  const asStringArray = (input: unknown): string[] =>
+    Array.isArray(input)
+      ? input.filter((elem): elem is string => typeof elem === "string")
+      : [];
+
+  const uniqueStrings = (input: string[]): string[] => [...new Set(input)];
+
+  type MaterializePlugin = Record<string, unknown> & { transform?: unknown };
+
+  const sdkTransformEnv = (): NodeJS.ProcessEnv =>
+    process.env.NESTIA_SDK_TRANSFORM === undefined
+      ? { NESTIA_SDK_TRANSFORM: "1" }
+      : {};
+
+  const materializePlugins = (input: unknown): MaterializePlugin[] => {
+    const plugins: MaterializePlugin[] = Array.isArray(input)
+      ? input
+          .filter((p) => typeof p === "object" && p !== null)
+          .map((p) => ({ ...(p as MaterializePlugin) }))
+      : [];
+    const typia: MaterializePlugin | undefined = plugins.find((p) =>
+      isTransform(p, "typia"),
+    );
+    const core: MaterializePlugin | undefined = plugins.find((p) =>
+      isTransform(p, "@nestia/core"),
+    );
+    return [
+      {
+        ...(typia ?? {}),
+        transform: "typia/lib/transform",
+        enabled: false,
+      },
+      normalizePlugin({
+        ...(core ?? {}),
+        transform: "@nestia/core/native/transform.cjs",
+      }),
+    ];
+  };
+
+  const normalizePlugin = (plugin: MaterializePlugin): MaterializePlugin => {
+    const output: MaterializePlugin = { ...plugin };
+    if (output.enabled === false) delete output.enabled;
+    return output;
+  };
+
+  const isTransform = (plugin: MaterializePlugin, name: string): boolean =>
+    typeof plugin.transform === "string" && plugin.transform.includes(name);
+
+  const findConfigFile = (cwd: string, project: string): string | undefined => {
+    const candidate: string = path.isAbsolute(project)
+      ? project
+      : path.resolve(cwd, project);
+    if (fs.existsSync(candidate)) return candidate;
+    if (path.isAbsolute(project) || project.includes(path.sep))
+      return undefined;
+
+    let current: string = path.resolve(cwd);
+    while (true) {
+      const next: string = path.join(current, project);
+      if (fs.existsSync(next)) return next;
+      const parent: string = path.dirname(current);
+      if (parent === current) return undefined;
+      current = parent;
+    }
+  };
+
+  const extractConfiguration = (
+    file: string,
+    loaded: unknown,
+  ): INestiaConfig | INestiaConfig[] => {
+    const candidates: unknown[] = [];
+    const collect = (value: unknown): void => {
+      if (isObject(value)) {
+        candidates.push(value.default);
+        candidates.push(value.NESTIA_CONFIG);
+        if (isObject(value.default)) {
+          candidates.push(value.default.default);
+          candidates.push(value.default.NESTIA_CONFIG);
+        }
+      }
+      candidates.push(value);
+    };
+    collect(loaded);
+    const matched: unknown = candidates.find(
+      (value) =>
+        Array.isArray(value) ||
+        (isObject(value) && Object.hasOwn(value, "input")),
+    );
+    if (matched === undefined)
+      throw new Error(
+        `invalid "${file}" data: configuration must be exported.`,
+      );
+    return matched as INestiaConfig | INestiaConfig[];
+  };
+
+  const loadMaterializedModule = async (file: string): Promise<unknown> => {
+    if (file.endsWith(".mjs")) {
+      const dynamicImport = new Function(
+        "specifier",
+        "return import(specifier)",
+      ) as (specifier: string) => Promise<unknown>;
+      return dynamicImport(pathToFileURL(file).href);
+    }
+    return require(file);
+  };
+
+  const assertPlugins = (
+    file: string,
+    input: unknown,
+  ): Array<Record<string, any>> => {
+    if (
+      Array.isArray(input) &&
+      input.every((elem) => typeof elem === "object" && elem !== null)
+    )
+      return input as Array<Record<string, any>>;
+    throw new Error(
+      `invalid "${file}" data: compilerOptions.plugins must be an array.`,
+    );
+  };
+
+  const assertConfigurations = (
+    file: string,
+    input: unknown[],
+  ): INestiaConfig[] => {
+    input.forEach((config, index) => assertConfig(file, config, index));
+    return input as INestiaConfig[];
+  };
+
+  const assertConfig = (file: string, input: unknown, index: number): void => {
+    if (isObject(input) === false)
+      throw new Error(
+        `invalid "${file}" data: configuration #${index} must be an object.`,
+      );
+    const config: INestiaConfig = input as unknown as INestiaConfig;
+    if (isInput(config.input) === false)
+      throw new Error(
+        `invalid "${file}" data: configuration #${index}.input is invalid.`,
+      );
+    for (const [key, value] of [
+      ["output", config.output],
+      ["distribute", config.distribute],
+      ["e2e", config.e2e],
+    ] as const)
+      if (value !== undefined && typeof value !== "string")
+        throw new Error(
+          `invalid "${file}" data: configuration #${index}.${key} must be a string.`,
+        );
+    for (const [key, value] of [
+      ["keyword", config.keyword],
+      ["simulate", config.simulate],
+      ["propagate", config.propagate],
+      ["clone", config.clone],
+      ["primitive", config.primitive],
+      ["assert", config.assert],
+      ["json", config.json],
+    ] as const)
+      if (value !== undefined && typeof value !== "boolean")
+        throw new Error(
+          `invalid "${file}" data: configuration #${index}.${key} must be a boolean.`,
+        );
+    if (config.swagger !== undefined && isSwagger(config.swagger) === false)
+      throw new Error(
+        `invalid "${file}" data: configuration #${index}.swagger is invalid.`,
+      );
+  };
+
+  const isInput = (input: unknown): input is INestiaConfig["input"] => {
+    if (
+      typeof input === "string" ||
+      typeof input === "function" ||
+      isStringArray(input)
+    )
+      return true;
+    if (isObject(input) === false) return false;
+    return (
+      isStringArray(input.include) &&
+      (input.exclude === undefined || isStringArray(input.exclude))
+    );
+  };
+
+  const isSwagger = (input: unknown): input is INestiaConfig.ISwaggerConfig => {
+    if (isObject(input) === false) return false;
+    return (
+      typeof input.output === "string" &&
+      (input.openapi === undefined ||
+        ["2.0", "3.0", "3.1", "3.2"].includes(input.openapi as string)) &&
+      (input.beautify === undefined ||
+        typeof input.beautify === "boolean" ||
+        typeof input.beautify === "number") &&
+      (input.additional === undefined ||
+        typeof input.additional === "boolean") &&
+      (input.decompose === undefined || typeof input.decompose === "boolean") &&
+      (input.operationId === undefined ||
+        typeof input.operationId === "function")
+    );
+  };
+
+  const isObject = (input: unknown): input is Record<string, unknown> =>
+    typeof input === "object" &&
+    input !== null &&
+    Array.isArray(input) === false;
+
+  const isStringArray = (input: unknown): input is string[] =>
+    Array.isArray(input) && input.every((elem) => typeof elem === "string");
+
+  const readChildOutput = (
+    error: unknown,
+    key: "stderr" | "stdout",
+  ): string => {
+    if (!error || typeof error !== "object" || !(key in error)) return "";
+    const value = (error as Record<string, unknown>)[key];
+    if (value === null || value === undefined) return "";
+    if (typeof value === "string") return value.trim();
+    if (Buffer.isBuffer(value)) return value.toString("utf8").trim();
+    return "";
+  };
+}