@nestia/migrate 14.0.1 → 14.0.3

package/src/executable/{bundle.js → bundle.ts}

@@ -1,16 +1,25 @@
+import cp from "node:child_process";
+import fs from "node:fs";
+
+import { run as runCached } from "./TemplateBundleCache";
+
 const { version } = require("../../../../package.json");
-const cp = require("child_process");
-const fs = require("fs");
 
 const ROOT = `${__dirname}/../..`;
 const ASSETS = `${ROOT}/assets`;
-const CATALOGS = require("js-yaml").load(
+const CATALOGS: Record<
+  string,
+  Record<string, { specifier: string }>
+> = require("js-yaml").load(
   fs.readFileSync(`${__dirname}/../../../../pnpm-lock.yaml`, "utf8"),
 ).catalogs;
-const TYPIA = CATALOGS.samchon;
+const TYPIA = CATALOGS.samchon!;
 const TYPESCRIPT = CATALOGS.typescript ?? {};
 
-const update = (content, options = {}) => {
+const update = (
+  content: string,
+  options: { sdkAggregate?: boolean } = {},
+): string => {
   const parsed = JSON.parse(content);
   for (const record of [
     parsed.dependencies ?? {},
@@ -47,7 +56,11 @@ const update = (content, options = {}) => {
   return JSON.stringify(parsed, null, 2);
 };
 
-const migratePackageJson = (parsed) => {
+const migratePackageJson = (parsed: {
+  scripts?: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}): void => {
   if (parsed.scripts)
     for (const [key, value] of Object.entries(parsed.scripts))
       if (typeof value === "string")
@@ -70,14 +83,14 @@ const migratePackageJson = (parsed) => {
 // current versions. Keep the rewrite line-targeted so quoted package names,
 // comments, ordering, and any anchors supplied by the upstream template remain
 // intact.
-const updateWorkspaceCatalog = (content) => {
-  const replace = (line) => {
+const updateWorkspaceCatalog = (content: string): string => {
+  const replace = (line: string): string => {
     const match = line.match(
       /^(\s+(?:"([^"]+)"|'([^']+)'|([^:\s]+)): (?:&[A-Za-z0-9_-]+ )?)\S[^\r\n]*(\r?)$/,
     );
     if (match === null) return line;
 
-    const name = match[2] ?? match[3] ?? match[4];
+    const name = (match[2] ?? match[3] ?? match[4])!;
     const specifier =
       name === "nestia" || name.startsWith("@nestia/")
         ? `^${version}`
@@ -88,7 +101,10 @@ const updateWorkspaceCatalog = (content) => {
   return content.split("\n").map(replace).join("\n");
 };
 
-const trimTemplateDependencies = (parsed) => {
+const trimTemplateDependencies = (parsed: {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}): void => {
   if (parsed.dependencies) {
     delete parsed.dependencies.commander;
     delete parsed.dependencies.inquirer;
@@ -100,7 +116,7 @@ const trimTemplateDependencies = (parsed) => {
   }
 };
 
-const normalizeScript = (script) =>
+const normalizeScript = (script: string): string =>
   script.replace(/(^|[^A-Za-z0-9_-])tsc(?=$|[^A-Za-z0-9_-])/g, "$1ttsc");
 
 const ARGUMENT_PARSER = `import { createInterface } from "node:readline/promises";
@@ -214,7 +230,7 @@ export namespace ArgumentParser {
 }
 `;
 
-const updateTsConfig = (content) => {
+const updateTsConfig = (content: string): string => {
   content = content.replace(
     /^\s*\{\s*"transform":\s*"typescript-transform-paths"\s*\},\r?\n/gm,
     "",
@@ -244,7 +260,13 @@ const bundle = async ({
   revision,
   exceptions,
   transform,
-}) => {
+}: {
+  mode: string;
+  repository: string;
+  revision: string;
+  exceptions?: readonly string[];
+  transform?: (key: string, value: string) => string;
+}): Promise<void> => {
   const root = `${__dirname}/../..`;
   const assets = `${root}/assets`;
   const template = `${assets}/${mode}`;
@@ -262,44 +284,68 @@ const bundle = async ({
     // on every platform: with core.autocrlf=true (the common Windows default)
     // the checkout would rewrite LF to CRLF and break the line-targeted
     // transforms below.
-    cp.execSync(
-      `git clone --config core.autocrlf=false https://github.com/samchon/${repository} ${mode}`,
-      {
-        cwd: ASSETS,
-      },
-    );
+    await fs.promises.mkdir(template, { recursive: true });
+    cp.execFileSync("git", ["init", "--quiet"], { cwd: template });
     // The template repositories are live projects; an unpinned clone lets any
     // upstream push break this build (samchon/nestia-start#632 did exactly
     // that), so every bundle checks out a reviewed revision.
-    cp.execSync(`git checkout ${revision}`, {
-      cwd: template,
-      stdio: "pipe",
-    });
+    cp.execFileSync(
+      "git",
+      [
+        "fetch",
+        "--quiet",
+        "--depth=1",
+        // This checkout is consumed and removed immediately. Fetch's default
+        // auto-maintenance can detach a writer into .git/objects after fetch
+        // returns, racing the awaited removal below on a cold CI build.
+        "--no-auto-maintenance",
+        `https://github.com/samchon/${repository}`,
+        revision,
+      ],
+      { cwd: template },
+    );
+    cp.execFileSync(
+      "git",
+      [
+        "-c",
+        "core.autocrlf=false",
+        "checkout",
+        "--quiet",
+        "--detach",
+        revision,
+      ],
+      {
+        cwd: template,
+        stdio: "pipe",
+      },
+    );
 
     // REMOVE VULNERABLE FILES
     for (const location of exceptions ?? [])
       await fs.promises.rm(`${template}/${location}`, { recursive: true });
   };
 
-  const iterate = (collection) => async (location) => {
-    const directory = await fs.promises.readdir(location);
-    for (const file of directory) {
-      const absolute = location + "/" + file;
-      const stats = await fs.promises.stat(absolute);
-      if (stats.isDirectory()) await iterate(collection)(absolute);
-      else {
-        const content = await fs.promises.readFile(absolute, "utf-8");
-        collection[
-          (() => {
-            const str = absolute.replace(template, "");
-            return str[0] === "/" ? str.substring(1) : str;
-          })()
-        ] = content;
+  const iterate =
+    (collection: Record<string, string>) =>
+    async (location: string): Promise<void> => {
+      const directory = await fs.promises.readdir(location);
+      for (const file of directory) {
+        const absolute = location + "/" + file;
+        const stats = await fs.promises.stat(absolute);
+        if (stats.isDirectory()) await iterate(collection)(absolute);
+        else {
+          const content = await fs.promises.readFile(absolute, "utf-8");
+          collection[
+            (() => {
+              const str = absolute.replace(template, "");
+              return str[0] === "/" ? str.substring(1) : str;
+            })()
+          ] = content;
+        }
       }
-    }
-  };
+    };
 
-  const archive = async (collection) => {
+  const archive = async (collection: Record<string, string>): Promise<void> => {
     const name = `${mode.toUpperCase()}_TEMPLATE`;
     const body = JSON.stringify(collection, null, 2);
     const content = `export const ${name}: Record<string, string> = ${body}`;
@@ -314,7 +360,7 @@ const bundle = async ({
     );
   };
 
-  const collection = {};
+  const collection: Record<string, string> = {};
   await clone();
   await iterate(collection)(template);
   if (transform)
@@ -327,12 +373,22 @@ const bundle = async ({
   await archive(collection);
 };
 
-const writeTransformedAsset = async (template, key, value) => {
+const writeTransformedAsset = async (
+  template: string,
+  key: string,
+  value: string,
+): Promise<string> => {
   await fs.promises.writeFile(`${template}/${key}`, value, "utf8");
   return value;
 };
 
-const main = async () => {
+/**
+ * Generates both pinned templates using the current release and catalog stamps.
+ *
+ * The complete script is a cache input because it contains the revisions,
+ * exclusions and every transformation rule. A hit still verifies output bytes.
+ */
+const generate = async () => {
   await bundle({
     mode: "nest",
     repository: "nestia-start",
@@ -399,6 +455,17 @@ const main = async () => {
     },
   });
 };
+const main = async () => {
+  const reused = await runCached({
+    inputs: [version, CATALOGS, fs.readFileSync(__filename, "utf8")],
+    outputs: ["NEST_TEMPLATE", "SDK_TEMPLATE"].map(
+      (name) => `${ROOT}/src/bundles/${name}.ts`,
+    ),
+    stampFile: `${ASSETS}/.bundle-cache.json`,
+    generate,
+  });
+  if (reused) console.log("Reuse verified migration template bundles.");
+};
 main().catch((exp) => {
   console.error(exp);
   process.exit(-1);

package/src/factories/ExpressionFactory.ts

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

package/src/factories/IdentifierFactory.ts

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

package/src/factories/LiteralFactory.ts

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

package/src/factories/StatementFactory.ts

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

package/src/factories/SupportedStringFormats.ts

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

package/src/factories/TypeFactory.ts

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

package/src/factories/TypeLiteralFactory.ts

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