@nestia/sdk 14.0.0 → 14.0.2

package/src/generates/internal/SdkHttpCloneReferencer.ts

@@ -1,13 +1,37 @@
+import { TsPrinter } from "@ttsc/factory";
+
 import { MetadataSchema, nameOf } from "../../internal/legacy";
+import { INestiaProject } from "../../structures/INestiaProject";
 import { IReflectType } from "../../structures/IReflectType";
 import { ITypedApplication } from "../../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
+import { ITypedMcpRoute } from "../../structures/ITypedMcpRoute";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
-import { StringUtil } from "../../utils/StringUtil";
+import { ImportDictionary } from "./ImportDictionary";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
+import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
 import { SdkWebSocketCloneProgrammer } from "./SdkWebSocketCloneProgrammer";
 
+/**
+ * Rewrites the routes to refer to the cloned DTOs.
+ *
+ * @evidence contracts/common.md#principled-implementation HTTP and MCP JSON types and their namespace/tag imports are emitted together from resolved metadata by the cloned declaration writer; WebSocket declarations retain their source types and redirect only cloned imports.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and three visitors.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The routes are rewritten in place, once.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneReferencer 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 SdkHttpCloneReferencer {
+  /**
+   * Rewrites the HTTP, MCP and WebSocket routes so their types and imports
+   * refer to the `structures` files.
+   *
+   * @evidence contracts/common.md#principled-implementation HTTP and MCP JSON routes use structural TypeNodes and the writer's registered imports. Empty and any/unknown forms retain their baked keyword distinction because they require no cloned component binding; WebSocket source types only redirect imports actually cloned.
+   * @evidence contracts/common.md#clear-and-simple-design One loop.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The routes are edited in place, as the generation owns them.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpCloneReferencer.replace 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 replace = (
     app: ITypedApplication,
     websocket: Set<string> = new Set(),
@@ -16,7 +40,7 @@ export namespace SdkHttpCloneReferencer {
     for (const route of app.routes)
       if (route.protocol === "http")
         visitHttpRoute({
-          directory,
+          project: app.project,
           route,
         });
       else if (route.protocol === "websocket")
@@ -25,43 +49,70 @@ export namespace SdkHttpCloneReferencer {
           directory,
           route,
         });
+      else if (route.protocol === "mcp") visitMcpRoute(app.project, route);
+  };
+
+  const visitMcpRoute = (
+    project: INestiaProject,
+    route: ITypedMcpRoute,
+  ): void => {
+    const importer = new ImportDictionary(
+      `${project.config.output}/functional/${route.accessor.join("/")}/index.ts`,
+    );
+    if (route.input && route.inputMetadata)
+      visitType({
+        importer,
+        project,
+        metadata: route.inputMetadata,
+        type: route.input.type,
+        name: (name) => (route.input!.type = { name }),
+      });
+    if (route.returnType && route.outputMetadata)
+      visitType({
+        importer,
+        project,
+        metadata: route.outputMetadata,
+        type: route.returnType,
+        name: (name) => (route.returnType = { name }),
+      });
+    route.imports = importer.toImports();
   };
 
   const visitHttpRoute = (props: {
-    directory: string;
+    project: INestiaProject;
     route: ITypedHttpRoute;
   }): void => {
-    const unique: Set<string> = new Set();
+    const importer = new ImportDictionary(
+      `${props.project.config.output}/functional/${props.route.accessor.join("/")}/index.ts`,
+    );
     for (const p of SdkHttpParameterProgrammer.getSignificant(
       props.route,
       true,
     ))
       visitType({
-        unique,
+        importer,
+        project: props.project,
         metadata: p.metadata,
         type: p.type,
         name: (name) => (p.type = { name }),
       });
     for (const v of Object.values(props.route.exceptions))
       visitType({
-        unique,
+        importer,
+        project: props.project,
         metadata: v.metadata,
         type: v.type,
         name: (name) => (v.type = { name }),
       });
     if (props.route.success.binary === false)
       visitType({
-        unique,
+        importer,
+        project: props.project,
         metadata: props.route.success.metadata,
         type: props.route.success.type,
         name: (name) => (props.route.success.type = { name }),
       });
-    props.route.imports = Array.from(unique).map((str) => ({
-      file: `${props.directory}/${str}`,
-      asterisk: null,
-      default: null,
-      elements: [str],
-    }));
+    props.route.imports = importer.toImports();
   };
 
   const visitWebSocketRoute = (props: {
@@ -113,20 +164,43 @@ export namespace SdkHttpCloneReferencer {
   };
 
   const visitType = (p: {
-    unique: Set<string>;
+    importer: ImportDictionary;
+    project: INestiaProject;
     metadata: MetadataSchema;
     type: IReflectType;
     name: (key: string) => void;
   }): void => {
-    const enroll = (key: string) => {
-      if (key.length && StringUtil.isImplicit(key) === false)
-        p.unique.add(StringUtil.accessorsOf(key)[0]!);
-    };
-    for (const alias of p.metadata.aliases) enroll(alias.type!.name);
-    for (const array of p.metadata.arrays) enroll(array.type!.name);
-    for (const tuple of p.metadata.tuples) enroll(tuple.type!.name);
-    for (const object of p.metadata.objects) enroll(object.type!.name);
-    p.name(nameOf(p.metadata));
+    // Empty and any/unknown metadata carries no structural declaration from
+    // which to recover its source-level keyword distinction. These forms require
+    // no cloned component binding; retain the producer's baked name (or declared
+    // route type for authored metadata without a bake).
+    if (
+      p.metadata.any ||
+      (p.metadata.nullable === false &&
+        p.metadata.escaped === null &&
+        p.metadata.rest === null &&
+        [
+          p.metadata.atomics,
+          p.metadata.constants,
+          p.metadata.templates,
+          p.metadata.arrays,
+          p.metadata.tuples,
+          p.metadata.objects,
+          p.metadata.aliases,
+          p.metadata.natives,
+          p.metadata.sets,
+          p.metadata.maps,
+          p.metadata.functions,
+        ].every((members) => members.length === 0))
+    ) {
+      p.name(nameOf(p.metadata) || getFullText(p.type));
+      return;
+    }
+    p.name(
+      new TsPrinter().print(
+        SdkTypeProgrammer.write(p.project)(p.importer)(p.metadata),
+      ),
+    );
   };
 }
 

package/src/generates/internal/SdkHttpFunctionProgrammer.ts

@@ -15,17 +15,37 @@ import { TypeFactory } from "../../factories/TypeFactory";
 import { sizeOf } from "../../internal/legacy";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedHttpRoute } from "../../structures/ITypedHttpRoute";
-import { StringUtil } from "../../utils/StringUtil";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkAliasCollection } from "./SdkAliasCollection";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkImportWizard } from "./SdkImportWizard";
 
+/**
+ * Writes the function of an HTTP route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace prints the exported async function with its parameters and the fetcher call and its headers.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and the body writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The names come from the parameter programmer.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpFunctionProgrammer 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 SdkHttpFunctionProgrammer {
+  /**
+   * Returns the exported async function of a route: `connection`, then the
+   * parameters, returning the output or `void`.
+   *
+   * @evidence contracts/common.md#principled-implementation The identifiers were decided once by the parameter programmer, and the body calls the plain or the encrypted fetcher.
+   * @evidence contracts/common.md#clear-and-simple-design One declaration built from the parameter and body helpers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The function uses the route's assigned name; SdkFileProgrammer may assign a private binding and export it under the public accessor when the module scope collides.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpFunctionProgrammer.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 =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute): Node => {
+      const names: SdkHttpParameterProgrammer.INames =
+        SdkHttpParameterProgrammer.getNames({ project, route });
       return factory.createFunctionDeclaration(
         [
           factory.createModifier(SyntaxKind.ExportKeyword),
@@ -36,7 +56,7 @@ export namespace SdkHttpFunctionProgrammer {
         undefined,
         [
           IdentifierFactory.parameter(
-            "connection",
+            names.connection,
             factory.createTypeReferenceNode(
               SdkImportWizard.IConnection(importer),
               route.headerObject !== null
@@ -59,21 +79,15 @@ export namespace SdkHttpFunctionProgrammer {
             ? factory.createTypeReferenceNode(`${route.name}.Output`)
             : factory.createTypeReferenceNode("void"),
         ]),
-        factory.createBlock(writeBody(project)(importer)(route), true),
+        factory.createBlock(writeBody(project)(importer)(route)(names), true),
       );
     };
 
   const writeBody =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
-    (route: ITypedHttpRoute): Statement[] => {
-      const access = (name: string): Expression =>
-        project.config.keyword === true
-          ? factory.createPropertyAccessExpression(
-              factory.createIdentifier("props"),
-              name,
-            )
-          : factory.createIdentifier(name);
+    (route: ITypedHttpRoute) =>
+    (names: SdkHttpParameterProgrammer.INames): Statement[] => {
       const fetch = () =>
         factory.createCallExpression(
           IdentifierFactory.access(
@@ -95,7 +109,7 @@ export namespace SdkHttpFunctionProgrammer {
               ? factory.createObjectLiteralExpression(
                   [
                     factory.createSpreadAssignment(
-                      factory.createIdentifier("connection"),
+                      factory.createIdentifier(names.connection),
                     ),
                     factory.createPropertyAssignment(
                       "headers",
@@ -103,7 +117,7 @@ export namespace SdkHttpFunctionProgrammer {
                         [
                           factory.createSpreadAssignment(
                             IdentifierFactory.access(
-                              factory.createIdentifier("connection"),
+                              factory.createIdentifier(names.connection),
                               "headers",
                             ),
                           ),
@@ -120,7 +134,7 @@ export namespace SdkHttpFunctionProgrammer {
                   ],
                   true,
                 )
-              : factory.createIdentifier("connection"),
+              : factory.createIdentifier(names.connection),
             factory.createObjectLiteralExpression(
               [
                 factory.createSpreadAssignment(
@@ -157,7 +171,7 @@ export namespace SdkHttpFunctionProgrammer {
               ],
               true,
             ),
-            ...(route.body ? [access(route.body.name)] : []),
+            ...(route.body ? [names.access(route.body)] : []),
             ...(project.config.json &&
             route.body !== null &&
             (route.body.contentType === "application/json" ||
@@ -171,14 +185,17 @@ export namespace SdkHttpFunctionProgrammer {
           ? factory.createConditionalExpression(
               factory.createStrictEquality(
                 factory.createTrue(),
-                factory.createIdentifier("connection.simulate"),
+                IdentifierFactory.access(
+                  factory.createIdentifier(names.connection),
+                  "simulate",
+                ),
               ),
               undefined,
               factory.createCallExpression(
                 factory.createIdentifier(`${route.name}.simulate`),
                 [],
                 [
-                  factory.createIdentifier("connection"),
+                  factory.createIdentifier(names.connection),
                   ...(SdkHttpParameterProgrammer.getArguments({
                     project,
                     route,
@@ -201,15 +218,15 @@ export namespace SdkHttpFunctionProgrammer {
                     factory.createIdentifier(SdkImportWizard.typia(importer)),
                     "assert",
                   ),
-                  [factory.createTypeQueryNode(access(p.name) as EntityName)],
-                  [access(p.name)],
+                  [factory.createTypeQueryNode(names.access(p) as EntityName)],
+                  [names.access(p)],
                 ),
               ),
             )
           : []),
         ...(route.success.setHeaders.length === 0
           ? [factory.createReturnStatement(output(false))]
-          : writeSetHeaders(project)(importer)(route)(output(true))),
+          : writeSetHeaders(project)(importer)(route)(names)(output(true))),
       ];
     };
 
@@ -217,16 +234,12 @@ export namespace SdkHttpFunctionProgrammer {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedHttpRoute) =>
+    (names: SdkHttpParameterProgrammer.INames) =>
     (condition: Expression): Statement[] => {
       const accessor = (x: string) => (y: string) =>
         x[0] === "[" ? `${x}${y}` : `${x}.${y}`;
-      const output: string = StringUtil.escapeDuplicate([
-        "connection",
-        ...SdkHttpParameterProgrammer.getSignificant(route, true).map(
-          (p) => p.name,
-        ),
-      ])("output");
-      const headers: string = accessor("connection")("headers");
+      const output: string = names.output;
+      const headers: string = accessor(names.connection)("headers");
       const data: string = project.config.propagate
         ? accessor(output)("data")
         : output;
@@ -248,9 +261,13 @@ export namespace SdkHttpFunctionProgrammer {
                 ],
               )
             : factory.createBinaryExpression(
-                factory.createIdentifier(
-                  accessor(headers)(tuple.target ?? tuple.source),
-                ),
+                // a target is a header name, which usually is no identifier
+                tuple.target !== undefined
+                  ? IdentifierFactory.access(
+                      factory.createIdentifier(headers),
+                      tuple.target,
+                    )
+                  : factory.createIdentifier(accessor(headers)(tuple.source)),
                 factory.createToken(SyntaxKind.EqualsToken),
                 factory.createIdentifier(accessor(data)(tuple.source)),
               ),

package/src/generates/internal/SdkHttpNamespaceProgrammer.ts

@@ -24,8 +24,28 @@ import { SdkAliasCollection } from "./SdkAliasCollection";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkHttpSimulationProgrammer } from "./SdkHttpSimulationProgrammer";
 import { SdkImportWizard } from "./SdkImportWizard";
+import { SdkPathTemplate } from "./SdkPathTemplate";
 
+/**
+ * Writes the namespace of an HTTP route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the route's types, its metadata, its path builder, and, when configured, its random, simulate, and stringify functions.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and four writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The parts follow the configuration.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpNamespaceProgrammer 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 SdkHttpNamespaceProgrammer {
+  /**
+   * Returns the namespace of a route: its types, `METADATA`, `path`, and, by
+   * configuration, `random`, `simulate`, and `stringify`.
+   *
+   * @evidence contracts/common.md#principled-implementation `stringify` exists only for a JSON or encrypted body when `json` is on, and the simulator only when `simulate` is on.
+   * @evidence contracts/common.md#clear-and-simple-design One declaration composed of the writers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The optional members follow the flags.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkHttpNamespaceProgrammer.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 =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
@@ -210,59 +230,28 @@ export namespace SdkHttpNamespaceProgrammer {
         false,
       );
       if (parameters.length === 0)
-        return out(factory.createStringLiteral(route.path));
-
-      const access = (name: string) =>
-        project.config.keyword === true ? `props.${name}` : name;
-      const template = () => {
-        const split: string[] = route.path.split(":");
-        if (split.length === 1) return factory.createStringLiteral(route.path);
-        return factory.createTemplateExpression(
-          factory.createTemplateHead(split[0]!),
-          split.slice(1).map((s, i, arr) => {
-            const name: string = s.split("/")[0]!;
-            return factory.createTemplateSpan(
-              factory.createCallExpression(
-                factory.createIdentifier("encodeURIComponent"),
-                undefined,
-                [
-                  factory.createBinaryExpression(
-                    factory.createCallChain(
-                      factory.createPropertyAccessChain(
-                        factory.createIdentifier(
-                          access(
-                            route.pathParameters.find((p) => p.field === name)!
-                              .name,
-                          ),
-                        ),
-                        factory.createToken(SyntaxKind.QuestionDotToken),
-                        "toString",
-                      ),
-                      undefined,
-                      undefined,
-                      [],
-                    ),
-                    factory.createToken(SyntaxKind.QuestionQuestionToken),
-                    factory.createStringLiteral("null"),
-                  ),
-                ],
-              ),
-              (i !== arr.length - 1
-                ? factory.createTemplateMiddle
-                : factory.createTemplateTail)(s.substring(name.length)),
-            );
+        return out(
+          SdkPathTemplate.compose({
+            importer,
+            path: route.path,
+            argument: () => factory.createIdentifier("undefined"),
           }),
         );
-      };
+
+      const names: SdkHttpParameterProgrammer.INames =
+        SdkHttpParameterProgrammer.getNames({ project, route });
+      const template = () =>
+        SdkPathTemplate.compose({
+          importer,
+          path: route.path,
+          argument: (name) =>
+            names.access(route.pathParameters.find((p) => p.field === name)!),
+        });
       if (route.queryObject === null && route.queryParameters.length === 0)
         return out(template());
 
       const block = (expr: Expression) => {
-        const computeName = (str: string): string =>
-          parameters.find((p) => p.name === str) !== undefined
-            ? computeName("_" + str)
-            : str;
-        const variables: string = computeName("variables");
+        const variables: string = names.variables;
         return factory.createBlock(
           [
             local(variables)("URLSearchParams")(
@@ -281,13 +270,13 @@ export namespace SdkHttpNamespaceProgrammer {
                       factory.createBindingElement(
                         undefined,
                         undefined,
-                        factory.createIdentifier("key"),
+                        factory.createIdentifier(names.key),
                         undefined,
                       ),
                       factory.createBindingElement(
                         undefined,
                         undefined,
-                        factory.createIdentifier("value"),
+                        factory.createIdentifier(names.value),
                         undefined,
                       ),
                     ]),
@@ -306,19 +295,19 @@ export namespace SdkHttpNamespaceProgrammer {
               factory.createIfStatement(
                 factory.createStrictEquality(
                   factory.createIdentifier("undefined"),
-                  factory.createIdentifier("value"),
+                  factory.createIdentifier(names.value),
                 ),
                 factory.createContinueStatement(),
                 factory.createIfStatement(
                   factory.createCallExpression(
                     factory.createIdentifier("Array.isArray"),
                     undefined,
-                    [factory.createIdentifier("value")],
+                    [factory.createIdentifier(names.value)],
                   ),
                   factory.createExpressionStatement(
                     factory.createCallExpression(
                       factory.createPropertyAccessExpression(
-                        factory.createIdentifier("value"),
+                        factory.createIdentifier(names.value),
                         factory.createIdentifier("forEach"),
                       ),
                       undefined,
@@ -326,7 +315,7 @@ export namespace SdkHttpNamespaceProgrammer {
                         factory.createArrowFunction(
                           undefined,
                           undefined,
-                          [IdentifierFactory.parameter("elem")],
+                          [IdentifierFactory.parameter(names.elem)],
                           undefined,
                           undefined,
                           factory.createCallExpression(
@@ -336,11 +325,11 @@ export namespace SdkHttpNamespaceProgrammer {
                             ),
                             undefined,
                             [
-                              factory.createIdentifier("key"),
+                              factory.createIdentifier(names.key),
                               factory.createCallExpression(
                                 factory.createIdentifier("String"),
                                 undefined,
-                                [factory.createIdentifier("elem")],
+                                [factory.createIdentifier(names.elem)],
                               ),
                             ],
                           ),
@@ -356,11 +345,11 @@ export namespace SdkHttpNamespaceProgrammer {
                       ),
                       undefined,
                       [
-                        factory.createIdentifier("key"),
+                        factory.createIdentifier(names.key),
                         factory.createCallExpression(
                           factory.createIdentifier("String"),
                           undefined,
-                          [factory.createIdentifier("value")],
+                          [factory.createIdentifier(names.value)],
                         ),
                       ],
                     ),
@@ -368,7 +357,7 @@ export namespace SdkHttpNamespaceProgrammer {
                 ),
               ),
             ),
-            local("location")("string")(template()),
+            local(names.location)("string")(template()),
             factory.createReturnStatement(
               factory.createConditionalExpression(
                 factory.createStrictEquality(
@@ -379,13 +368,13 @@ export namespace SdkHttpNamespaceProgrammer {
                   ),
                 ),
                 undefined,
-                factory.createIdentifier("location"),
+                factory.createIdentifier(names.location),
                 undefined,
                 factory.createTemplateExpression(
                   factory.createTemplateHead(""),
                   [
                     factory.createTemplateSpan(
-                      factory.createIdentifier("location"),
+                      factory.createIdentifier(names.location),
                       factory.createTemplateMiddle("?"),
                     ),
                     factory.createTemplateSpan(
@@ -412,11 +401,11 @@ export namespace SdkHttpNamespaceProgrammer {
           block(
             route.queryObject.metadata.required === false
               ? factory.createBinaryExpression(
-                  factory.createIdentifier(route.queryObject.name),
+                  names.access(route.queryObject),
                   factory.createToken(SyntaxKind.QuestionQuestionToken),
                   factory.createObjectLiteralExpression([], false),
                 )
-              : factory.createIdentifier(access(route.queryObject.name)),
+              : names.access(route.queryObject),
           ),
         );
       return out(
@@ -426,7 +415,7 @@ export namespace SdkHttpNamespaceProgrammer {
               ...(route.queryObject
                 ? [
                     factory.createSpreadAssignment(
-                      factory.createIdentifier(access(route.queryObject.name)),
+                      names.access(route.queryObject),
                     ),
                   ]
                 : []),
@@ -435,7 +424,7 @@ export namespace SdkHttpNamespaceProgrammer {
                   NamingConvention.variable(q.field!)
                     ? q.field!
                     : factory.createStringLiteral(q.field!),
-                  factory.createIdentifier(access(q.name)),
+                  names.access(q),
                 ),
               ),
             ],