@nestia/sdk 14.0.0 → 14.0.2

package/src/generates/internal/SdkDistributionComposer.ts

@@ -4,85 +4,206 @@ import path from "path";
 
 import { INestiaConfig } from "../../INestiaConfig";
 
+/**
+ * Composes the npm package of the SDK in the distribution directory.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace copies the bundle, fills its paths in, and installs the dependencies at the versions the project uses.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and the private steps.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Each filesystem step resolves against the distribution directory; no process-global directory or foreign method is changed.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Native paths use path.relative/path.join and generated paths use slash separators. npm receives an argument vector and an explicit cwd. POSIX launches npm directly; Windows launches the npm-cli.js shipped beside the first npm.cmd on PATH through Node because a cmd shim itself requires shell interpretation. A nonstandard Windows npm shim lacking that adjacent npm installation is rejected explicitly.
+ */
 export namespace SdkDistributionComposer {
+  /**
+   * Prepares the distribution package once: files, paths, and dependencies, and
+   * does nothing when the package is already configured.
+   *
+   * @evidence contracts/common.md#principled-implementation The package counts as configured when it holds `@nestia/fetcher`, which is installed last with its peers, so an interrupted setup runs again. The caller directory is captured once, and every output path and package-manager cwd is explicit.
+   * @evidence contracts/common.md#clear-and-simple-design One function of sequential steps.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No process-global directory is changed, so independent compositions retain their own destinations.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Existence of the two package files is the filesystem's own answer, and the bundle files are copied over any file of the same name in a distribution directory that is not yet configured, so an interrupted setup repeats the copy.
+   */
   export const compose = async (props: {
     config: INestiaConfig;
     mcp: boolean;
     websocket: boolean;
   }) => {
-    if (!fs.existsSync(props.config.distribute!))
-      await fs.promises.mkdir(props.config.distribute!, { recursive: true });
-
     const root: string = process.cwd();
+    const directory: string = path.resolve(props.config.distribute!);
     const output: string = path.resolve(props.config.output!);
-    process.chdir(props.config.distribute!);
-    try {
-      if (await configured()) return;
-
-      // COPY FILES
-      console.log("Composing SDK distribution environments...");
-      for (const file of await fs.promises.readdir(BUNDLE))
-        await fs.promises.copyFile(`${BUNDLE}/${file}`, file);
+    await fs.promises.mkdir(directory, { recursive: true });
+    if (await configured(directory)) return;
 
-      // CONFIGURE PATHS
-      for (const file of ["package.json", "tsconfig.json"])
-        await replace({ root, output })(file);
+    console.log("Composing SDK distribution environments...");
+    for (const file of await fs.promises.readdir(BUNDLE))
+      await fs.promises.copyFile(
+        path.join(BUNDLE, file),
+        path.join(directory, file),
+      );
+    for (const file of ["package.json", "tsconfig.json"])
+      await replace({ root, output, directory })(file);
 
-      // INSTALL PACKAGES
-      const v: IDependencies = await dependencies({
-        websocket: props.websocket,
-      });
-      execute("npm install --save-dev rimraf");
-      execute(`npm install --save @nestia/fetcher@${v.version}`);
-      execute(`npm install --save typia@${v.typia}`);
-      if (props.mcp && v.mcp !== undefined)
-        execute(`npm install --save @modelcontextprotocol/sdk@${v.mcp}`);
-      if (props.websocket && v.tgrid !== undefined)
-        execute(`npm install --save tgrid@${v.tgrid}`);
-      execute("npx typia setup --manager npm");
-    } finally {
-      process.chdir(root);
-    }
+    // Compile with ttsc, which applies typia's transform; typia no longer has
+    // a setup command. Install each dependency kind together so an interrupted
+    // setup cannot mark @nestia/fetcher configured before its runtime peers.
+    const v: IDependencies = await dependencies({
+      root,
+      websocket: props.websocket,
+    });
+    execute(directory, [
+      "install",
+      "--save-dev",
+      "rimraf",
+      `ttsc@${v.ttsc}`,
+      `typescript@${v.typescript}`,
+    ]);
+    execute(directory, [
+      "install",
+      "--save",
+      `@nestia/fetcher@${v.version}`,
+      `typia@${v.typia}`,
+      ...(props.mcp && v.mcp !== undefined
+        ? [`@modelcontextprotocol/sdk@${v.mcp}`]
+        : []),
+      ...(props.websocket && v.tgrid !== undefined ? [`tgrid@${v.tgrid}`] : []),
+    ]);
   };
 
-  const configured = async (): Promise<boolean> =>
-    ["package.json", "tsconfig.json"].every(fs.existsSync) &&
+  const configured = async (directory: string): Promise<boolean> =>
+    ["package.json", "tsconfig.json"].every((file) =>
+      fs.existsSync(path.join(directory, file)),
+    ) &&
     (await (async () => {
       const content = JSON.parse(
-        await fs.promises.readFile("package.json", "utf8"),
+        await fs.promises.readFile(
+          path.join(directory, "package.json"),
+          "utf8",
+        ),
       );
       return !!content.dependencies?.["@nestia/fetcher"];
     })());
 
-  const execute = (command: string) => {
-    console.log(`  - ${command}`);
-    cp.execSync(command, { stdio: "ignore" });
+  const execute = (cwd: string, args: string[]): void => {
+    console.log(`  - npm ${args.join(" ")}`);
+    if (process.platform !== "win32")
+      cp.execFileSync("npm", args, { cwd, stdio: "ignore" });
+    else {
+      // Windows cannot execute npm.cmd without cmd.exe. Launch the JavaScript
+      // entry point installed beside that shim instead, so dependency ranges
+      // and paths never pass through a shell's metacharacter interpretation.
+      const directories = (process.env.PATH ?? "").split(path.delimiter);
+      const directory = directories.find((entry) =>
+        fs.existsSync(path.join(entry, "npm.cmd")),
+      );
+      const cli =
+        directory === undefined
+          ? undefined
+          : [
+              path.join(directory, "node_modules/npm/bin/npm-cli.js"),
+              path.resolve(directory, "../npm/bin/npm-cli.js"),
+            ].find((entry) => fs.existsSync(entry));
+      if (cli === undefined)
+        throw new Error(
+          "Unable to locate npm's JavaScript entry point beside npm.cmd on PATH.",
+        );
+      cp.execFileSync(process.execPath, [cli, ...args], {
+        cwd,
+        stdio: "ignore",
+      });
+    }
   };
 
   const replace =
-    (props: { root: string; output: string }) =>
+    (props: { root: string; output: string; directory: string }) =>
     async (file: string): Promise<void> => {
       const relative = (from: string) => (to: string) =>
         path.relative(from, to).split("\\").join("/");
-      const root: string = relative(process.cwd())(props.root);
-      const output: string = relative(process.cwd())(props.output);
-      const current: string = relative(props.root)(process.cwd());
-
-      const content: string = await fs.promises.readFile(file, "utf8");
+      const root: string = relative(props.directory)(props.root);
+      const output: string = relative(props.directory)(props.output);
+      const current: string = relative(props.root)(props.directory);
+      const replacements: Record<string, string> = { root, output, current };
+      const location: string = path.join(props.directory, file);
+      const content: unknown = JSON.parse(
+        await fs.promises.readFile(location, "utf8"),
+      );
+      const substitute = (value: unknown): unknown => {
+        if (typeof value === "string")
+          return value.replace(
+            /\$\{(root|output|current)\}/g,
+            (_match, key: string) => replacements[key]!,
+          );
+        if (Array.isArray(value)) return value.map(substitute);
+        if (value !== null && typeof value === "object")
+          return Object.fromEntries(
+            Object.entries(value).map(([key, element]) => [
+              key,
+              substitute(element),
+            ]),
+          );
+        return value;
+      };
       await fs.promises.writeFile(
-        file,
-        content
-          .split("${root}")
-          .join(root)
-          .split("${output}")
-          .join(output)
-          .split("${current}")
-          .join(current),
+        location,
+        JSON.stringify(substitute(content), null, 2) + "\n",
         "utf8",
       );
     };
 
+  /**
+   * The version of a package the project installed, exactly: the staged package
+   * must run the typia, and compile with the ttsc and TypeScript, the project
+   * itself uses, with the tgrid and MCP SDK its WebSocket and MCP functions
+   * import. `@nestia/sdk`'s own specifier is only the fallback, and a
+   * workspace's `catalog:` one names no version npm could install.
+   */
+  const installed = (
+    root: string,
+    name: string,
+    fallback: string | undefined,
+  ): string | undefined =>
+    manifestVersion(root, name) ??
+    (fallback !== undefined && fallback.startsWith("catalog:") === false
+      ? fallback
+      : undefined);
+
+  /**
+   * The version in the manifest of the package as installed. Not every package
+   * exports its `package.json`, as tgrid does not, and a subpath export may map
+   * it to a nested manifest of no name, as `@modelcontextprotocol/sdk` maps it
+   * to `dist/cjs/package.json`; so the manifest is the nearest `package.json`
+   * naming the package, at or above what the request resolves to.
+   */
+  const manifestVersion = (root: string, name: string): string | undefined => {
+    for (const request of [`${name}/package.json`, name]) {
+      let file: string;
+      try {
+        file = require.resolve(request, { paths: [root, __dirname] });
+      } catch {
+        continue;
+      }
+      for (let directory: string = path.dirname(file); ; ) {
+        try {
+          const json: { name?: unknown; version?: unknown } = JSON.parse(
+            fs.readFileSync(path.join(directory, "package.json"), "utf8"),
+          );
+          if (
+            json.name === name &&
+            typeof json.version === "string" &&
+            json.version.length !== 0
+          )
+            return json.version;
+        } catch {}
+        const parent: string = path.dirname(directory);
+        if (parent === directory) break;
+        directory = parent;
+      }
+    }
+    return undefined;
+  };
+
   const dependencies = async (opts: {
+    root: string;
     websocket: boolean;
   }): Promise<IDependencies> => {
     const content: string = await fs.promises.readFile(
@@ -98,20 +219,22 @@ export namespace SdkDistributionComposer {
       ...json.devDependencies,
       ...json.dependencies,
     };
-    const required = (key: "version" | "typia"): string => {
-      const value: string | undefined =
-        key === "version" ? json.version : dependencies[key];
+    const required = (key: string, value: string | undefined): string => {
       if (typeof value !== "string" || value.length === 0)
         throw new Error(
           `Unable to resolve ${key} version for SDK distribution.`,
         );
       return value;
     };
+    const version = (name: string): string | undefined =>
+      installed(opts.root, name, dependencies[name]);
     return {
-      version: required("version"),
-      typia: required("typia"),
-      tgrid: opts.websocket ? dependencies.tgrid : undefined,
-      mcp: dependencies["@modelcontextprotocol/sdk"],
+      version: required("@nestia/fetcher", json.version),
+      typia: required("typia", version("typia")),
+      ttsc: required("ttsc", version("ttsc")),
+      typescript: required("typescript", version("typescript")),
+      tgrid: opts.websocket ? version("tgrid") : undefined,
+      mcp: version("@modelcontextprotocol/sdk"),
     };
   };
 }
@@ -119,6 +242,8 @@ export namespace SdkDistributionComposer {
 interface IDependencies {
   version: string;
   typia: string;
+  ttsc: string;
+  typescript: string;
   tgrid: string | undefined;
   mcp: string | undefined;
 }

package/src/generates/internal/SdkFileProgrammer.ts

@@ -1,4 +1,4 @@
-import { type Node, factory } from "@ttsc/factory";
+import { type Node, SyntaxKind, factory } from "@ttsc/factory";
 import fs from "fs";
 
 import { INestiaProject } from "../../structures/INestiaProject";
@@ -7,6 +7,7 @@ import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
 import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
 import { MapUtil } from "../../utils/MapUtil";
+import { StringUtil } from "../../utils/StringUtil";
 import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkHttpRouteProgrammer } from "./SdkHttpRouteProgrammer";
@@ -14,10 +15,28 @@ import { SdkMcpRouteProgrammer } from "./SdkMcpRouteProgrammer";
 import { SdkRouteDirectory } from "./SdkRouteDirectory";
 import { SdkWebSocketRouteProgrammer } from "./SdkWebSocketRouteProgrammer";
 
+/**
+ * Writes the functional part of the SDK.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace builds the directory tree of the routes by accessor and prints one `index.ts` per directory.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and two private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The tree follows the accessors of the routes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Node mkdir creates native directories from the configured output and analyzed identifier accessors; ImportDictionary separately renders relative module specifiers with forward slashes. No filesystem case equivalence is inferred from route names.
+ */
 export namespace SdkFileProgrammer {
   /* ---------------------------------------------------------
         CONSTRUCTOR
     --------------------------------------------------------- */
+  /**
+   * Writes the `functional` tree of the SDK from the routes' accessors.
+   *
+   * @evidence contracts/common.md#principled-implementation A route lands in the directory of its accessor without the last segment, and each directory exports its children as namespaces.
+   * @evidence contracts/common.md#clear-and-simple-design One tree build and one recursive writer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The order of routes is the analysis order.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation The recursive writer passes output paths to Node fs and FilePrinter, which accept the slash suffixes on Windows and POSIX. Accessor analysis supplies valid namespace names; module specifier spelling remains the importer’s separate responsibility.
+   */
   export const generate = async (app: ITypedApplication): Promise<void> => {
     // CONSTRUCT FOLDER TREE
     const root: SdkRouteDirectory = new SdkRouteDirectory(null, "functional");
@@ -70,22 +89,75 @@ export namespace SdkFileProgrammer {
         statements.push(FilePrinter.enter());
 
       // ITERATE ROUTES
-      const importer: ImportDictionary = new ImportDictionary(
-        `${outDir}/index.ts`,
-      );
-      directory.routes.forEach((route, i) => {
-        if (!(project.config.clone === true && route.protocol === "http"))
-          importer.declarations(route.imports);
-        statements.push(
-          ...(route.protocol === "http"
-            ? SdkHttpRouteProgrammer.write(project)(importer)(route)
-            : route.protocol === "websocket"
-              ? SdkWebSocketRouteProgrammer.write(project)(importer)(route)
-              : SdkMcpRouteProgrammer.write(project)(importer)(route)),
+      const write = (locals: Map<AnyRoute, string>) => {
+        const importer: ImportDictionary = new ImportDictionary(
+          `${outDir}/index.ts`,
         );
-        if (i !== directory.routes.length - 1)
-          statements.push(FilePrinter.enter());
-      });
+        const output: Node[] = [];
+        directory.routes.forEach((route, i) => {
+          if (!(project.config.clone === true && route.protocol === "http"))
+            importer.declarations(route.imports);
+          const local: string | undefined = locals.get(route);
+          const target: AnyRoute =
+            local === undefined ? route : { ...route, name: local };
+          const written: Node[] =
+            target.protocol === "http"
+              ? SdkHttpRouteProgrammer.write(project)(importer)(target)
+              : target.protocol === "websocket"
+                ? SdkWebSocketRouteProgrammer.write(project)(importer)(target)
+                : SdkMcpRouteProgrammer.write(project)(importer)(target);
+          if (local !== undefined) {
+            written.forEach(unexport);
+            written.push(
+              factory.createExportDeclaration(
+                undefined,
+                false,
+                factory.createNamedExports([
+                  factory.createExportSpecifier(false, local, route.name),
+                ]),
+                undefined,
+              ),
+            );
+          }
+          output.push(...written);
+          if (i !== directory.routes.length - 1)
+            output.push(FilePrinter.enter());
+        });
+        return { importer, statements: output };
+      };
+
+      // A route's function and namespace are declared in the module scope,
+      // where the file's imports and the globals its bodies reference live
+      // too. A route named like one of them shadows it for the whole file, or
+      // conflicts with the import, so the SDK would not compile (#1647); a
+      // method named `tags` whose path parameter is typed with `tags.Format`
+      // is enough. Its public name cannot change, so it is declared under a
+      // local one and exported as itself.
+      let file = write(new Map());
+      const scope: Set<string> = new Set([
+        ...file.importer.locals(),
+        ...MODULE_GLOBALS,
+      ]);
+      const shadowing: AnyRoute[] = directory.routes.filter((r) =>
+        scope.has(r.name),
+      );
+      if (shadowing.length !== 0) {
+        // each local name distinct from the scope, the routes, and the other
+        // locals
+        const taken: string[] = [
+          ...scope,
+          ...directory.routes.map((r) => r.name),
+        ];
+        const locals: Map<AnyRoute, string> = new Map();
+        for (const route of shadowing) {
+          const local: string = StringUtil.escapeDuplicate(taken)(route.name);
+          taken.push(local);
+          locals.set(route, local);
+        }
+        file = write(locals);
+      }
+      const importer: ImportDictionary = file.importer;
+      statements.push(...file.statements);
 
       // FINALIZE THE CONTENT
       if (directory.routes.length !== 0)
@@ -109,3 +181,41 @@ export namespace SdkFileProgrammer {
       });
     };
 }
+
+type AnyRoute = ITypedHttpRoute | ITypedWebSocketRoute | ITypedMcpRoute;
+
+/**
+ * Globals the generated route bodies reference, and names TypeScript reserves
+ * in a module's top-level scope: `Promise` in one with async functions, and
+ * `require` and `exports` in a CommonJS one.
+ */
+const MODULE_GLOBALS: string[] = [
+  "Array",
+  "Error",
+  "JSON",
+  "Object",
+  "Promise",
+  "ReadableStream",
+  "String",
+  "URLSearchParams",
+  "encodeURIComponent",
+  "exports",
+  "require",
+  "undefined",
+];
+
+/** Drops the `export` modifier of a route's function or namespace. */
+const unexport = (node: Node): void => {
+  const declaration = node as {
+    kind: string;
+    modifiers?: Array<{ kind: string; token?: string }>;
+  };
+  if (
+    (declaration.kind === "FunctionDeclaration" ||
+      declaration.kind === "ModuleDeclaration") &&
+    declaration.modifiers !== undefined
+  )
+    declaration.modifiers = declaration.modifiers.filter(
+      (m) => m.token !== SyntaxKind.ExportKeyword,
+    );
+};

package/src/generates/internal/SdkHttpCloneProgrammer.ts

@@ -15,13 +15,42 @@ import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 
+/**
+ * Composes the DTO declarations of the HTTP routes.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace turns each named object, alias and recursive collection into a declaration, placed in a tree of modules by its dotted name.
+ * @evidence contracts/common.md#clear-and-simple-design One declaration-tree operation dispatches object, alias and recursive collection bodies through their owning writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Implicit object and alias names are not declared; native-marked recursive collections supply named declarations so recursive references have a definition.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkHttpCloneProgrammer {
+  /**
+   * A module of the declaration tree: its name, its children, and the writer of
+   * its own declaration.
+   *
+   * @evidence contracts/common.md#principled-implementation A module without a writer only holds children.
+   * @evidence contracts/common.md#clear-and-simple-design A three-member record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneProgrammer.IModule composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IModule {
     name: string;
     children: Map<string, IModule>;
     programmer: null | ((importer: ImportDictionary) => Node);
   }
 
+  /**
+   * Returns the declaration tree of the application's named types, keyed by
+   * their top-level name.
+   *
+   * @evidence contracts/common.md#principled-implementation Named objects and aliases are registered, and implicit names are skipped. Recursive arrays and tuples also need declarations: each writes one collection body whose nested uses are named references. Finite and object-mediated collections stay inline.
+   * @evidence contracts/common.md#clear-and-simple-design Four collection loops feed the same declaration tree, so all named forms share namespace and import decisions.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The implicit test is the shared definition.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write = (app: ITypedApplication): Map<string, IModule> => {
     // COMPOSE THE DICTIONARY
     const dict: Map<string, IModule> = new Map();
@@ -39,6 +68,32 @@ export namespace SdkHttpCloneProgrammer {
           name: k,
           programmer: (importer) => writeAlias(app.project)(importer)(v),
         });
+    for (const [k, v] of app.collection.arrays.entries())
+      if (v.recursive)
+        prepare({
+          dict,
+          name: k,
+          programmer: (importer) =>
+            factory.createTypeAliasDeclaration(
+              [factory.createModifier(SyntaxKind.ExportKeyword)],
+              StringUtil.accessorsOf(k).at(-1)!,
+              [],
+              SdkTypeProgrammer.write_array_type(app.project)(importer)(v),
+            ),
+        });
+    for (const [k, v] of app.collection.tuples.entries())
+      if (v.recursive)
+        prepare({
+          dict,
+          name: k,
+          programmer: (importer) =>
+            factory.createTypeAliasDeclaration(
+              [factory.createModifier(SyntaxKind.ExportKeyword)],
+              StringUtil.accessorsOf(k).at(-1)!,
+              [],
+              SdkTypeProgrammer.write_tuple_type(app.project)(importer)(v),
+            ),
+        });
     return dict;
   };