@nestia/migrate 14.0.0 → 14.0.2

package/src/programmers/NestiaMigrateApiNamespaceProgrammer.ts

@@ -9,18 +9,53 @@ import { TypeFactory } from "../factories/TypeFactory";
 import ts from "../internal/ts";
 import { INestiaMigrateConfig } from "../structures/INestiaMigrateConfig";
 import { FilePrinter } from "../utils/FilePrinter";
+import { PathTemplate } from "../utils/PathTemplate";
+import { RequestBody } from "../utils/RequestBody";
 import { NestiaMigrateApiSimulationProgrammer } from "./NestiaMigrateApiSimulationProgrammer";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the namespace that accompanies the function of a route: its types,
+ * its metadata, its path builder, and, in simulation mode, its simulator.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace declares the `Props`, `Query`, `Body`, `Headers`, and `Response` types from the schemas, the route metadata the fetcher reads, the `path` function that fills the parameters into the template, and the simulator members.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function, one public path-call builder shared with the simulation programmer, and private helpers per member.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The output derives from the route and the configuration.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiNamespaceProgrammer {
+  /**
+   * The input of one namespace: the configuration, the components, the
+   * importer, and the route.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds exactly what the namespace generation needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the fields.
+   */
   export interface IContext {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
+
+    /** File-local import collector shared with the surrounding file writer. */
     importer: NestiaMigrateImportProgrammer;
+
+    /** Analyzed operation, with the accessor chosen for this generation. */
     route: IHttpMigrateRoute;
   }
 
+  /**
+   * Returns the namespace declaration of a route.
+   *
+   * @evidence contracts/common.md#principled-implementation The members are written in a fixed order: types, metadata, path function, and the random and simulate members when simulation is enabled.
+   * @evidence contracts/common.md#clear-and-simple-design One function composing the private writers.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The members follow the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (ctx: IContext): ts.ModuleDeclaration => {
     const types: ts.TypeAliasDeclaration[] = writeTypes(ctx);
     return factory.createModuleDeclaration(
@@ -43,6 +78,15 @@ export namespace NestiaMigrateApiNamespaceProgrammer {
     );
   };
 
+  /**
+   * Returns the call expression of the route's `path` function with the
+   * arguments the configuration selects.
+   *
+   * @evidence contracts/common.md#principled-implementation In keyword mode the arguments are the `props` object and otherwise the path and query parameters in order, so the same call is valid in both modes.
+   * @evidence contracts/common.md#clear-and-simple-design One function shared by the simulator and the namespace.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The arguments follow the configuration.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the two argument forms.
+   */
   export const writePathCallExpression = (
     config: INestiaMigrateConfig,
     route: IHttpMigrateRoute,
@@ -116,7 +160,9 @@ export namespace NestiaMigrateApiNamespaceProgrammer {
             required: [
               ...ctx.route.parameters.map((p) => p.key),
               ...(ctx.route.query ? [ctx.route.query.key] : []),
-              ...(ctx.route.body ? [ctx.route.body.key] : []),
+              ...(ctx.route.body && RequestBody.optional(ctx.route) === false
+                ? [ctx.route.body.key]
+                : []),
             ],
           },
         }),
@@ -280,32 +326,49 @@ export namespace NestiaMigrateApiNamespaceProgrammer {
         ),
       );
     const template = () => {
-      const path: string = getPath(ctx.route);
-      const split: string[] = path.split(":");
-      if (split.length === 1) return factory.createStringLiteral(path);
+      // the document's template delimits each parameter; the emended path's
+      // `:id.json` would not tell the name from the literal after it
+      const segments: PathTemplate.ISegment[] = PathTemplate.segments(
+        ctx.route,
+      );
+      if (segments.every((segment) => segment.type === "literal"))
+        return factory.createStringLiteral(getPath(ctx.route));
+      const literals: string[] = [""];
+      const parameters: IHttpMigrateRoute.IParameter[] = [];
+      for (const segment of segments)
+        if (segment.type === "literal")
+          literals[literals.length - 1] += segment.value;
+        else {
+          parameters.push(segment.parameter);
+          literals.push("");
+        }
       return factory.createTemplateExpression(
-        factory.createTemplateHead(split[0]!),
-        split.slice(1).map((s, i, arr) => {
-          const name: string = s.split("/")[0]!;
-          return factory.createTemplateSpan(
+        factory.createTemplateHead(literals[0]!),
+        parameters.map((parameter, i) =>
+          factory.createTemplateSpan(
+            // URI-encoded, "null" when nullish, and a dot segment refused
             factory.createCallExpression(
-              factory.createIdentifier("encodeURIComponent"),
+              IdentifierFactory.access(
+                factory.createIdentifier(
+                  ctx.importer.external({
+                    type: "instance",
+                    library: "@nestia/fetcher",
+                    name: "PathParameter",
+                  }),
+                ),
+                "encode",
+              ),
               undefined,
               [
-                factory.createBinaryExpression(
-                  property(
-                    ctx.route.parameters.find((p) => p.name === name)!.key,
-                  ),
-                  factory.createToken(SyntaxKind.QuestionQuestionToken),
-                  factory.createStringLiteral("null"),
-                ),
+                factory.createStringLiteral(parameter.key),
+                property(parameter.key),
               ],
             ),
-            (i !== arr.length - 1
+            (i !== parameters.length - 1
               ? factory.createTemplateMiddle
-              : factory.createTemplateTail)(s.substring(name.length)),
-          );
-        }),
+              : factory.createTemplateTail)(literals[i + 1]!),
+          ),
+        ),
       );
     };
     if (!ctx.route.query) return out(template());

package/src/programmers/NestiaMigrateApiProgrammer.ts

@@ -8,7 +8,25 @@ import { NestiaMigrateApiFileProgrammer } from "./NestiaMigrateApiFileProgrammer
 import { NestiaMigrateDtoProgrammer } from "./NestiaMigrateDtoProgrammer";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 
+/**
+ * Generates the functional API files and, for an SDK project, the DTO structure
+ * files.
+ *
+ * @evidence contracts/common.md#principled-implementation Routes are grouped by namespace path in a hash map, each parent namespace is given its child, and each namespace becomes one `index.ts`; the DTO files are written per top-level component name.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and two private helpers for the DTO files.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the accessors of the routes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiProgrammer {
+  /**
+   * Returns the map from file path to content of the functional API, with the
+   * DTO files for an SDK project.
+   *
+   * @evidence contracts/common.md#principled-implementation The grouping creates every ancestor namespace so that each level has an index, and the paths differ between the two modes only by their root.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the accessors.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (ctx: INestiaMigrateContext): Record<string, string> => {
     const dict: HashMap<string[], NestiaMigrateApiFileProgrammer.IProps> =
       new HashMap(

package/src/programmers/NestiaMigrateApiSimulationProgrammer.ts

@@ -12,14 +12,48 @@ import { NestiaMigrateApiNamespaceProgrammer } from "./NestiaMigrateApiNamespace
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the mockup simulator members of a route: a random response and a
+ * simulate function that validates the request first.
+ *
+ * @evidence contracts/common.md#principled-implementation The random member calls `typia.random` for the response type, and the simulate function validates the parameters, query, body, and headers with `typia.assert` through the fetcher's simulator, so an invalid simulated request throws the error the real server answers.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions and one private assertion writer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The simulation follows the schemas of the route.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiSimulationProgrammer {
+  /**
+   * The input of the simulation members: the configuration, the components, the
+   * importer, and the route.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds exactly what the generation needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the fields.
+   */
   export interface IContext {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
+
+    /** File-local import collector shared with the surrounding file writer. */
     importer: NestiaMigrateImportProgrammer;
+
+    /** Analyzed operation, with the accessor chosen for this generation. */
     route: IHttpMigrateRoute;
   }
 
+  /**
+   * Returns the `random` constant: a function that returns a random value of
+   * the response type.
+   *
+   * @evidence contracts/common.md#principled-implementation The response schema is written as a type and given to `typia.random`, and a route without a response uses `void`.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The value is produced by typia at run time.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const random = (ctx: IContext) => {
     const output = ctx.route.success
       ? NestiaMigrateSchemaProgrammer.write({
@@ -54,6 +88,15 @@ export namespace NestiaMigrateApiSimulationProgrammer {
     );
   };
 
+  /**
+   * Returns the `simulate` constant: a function with the route's parameters
+   * that validates the request and returns a random response.
+   *
+   * @evidence contracts/common.md#principled-implementation The parameters are those of the real function, the assertions run first, and an unused connection is renamed so the compiler does not report it.
+   * @evidence contracts/common.md#clear-and-simple-design One expression over the shared parameter builder.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The validation is generated from the same schemas as the real function's types.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const simulate = (ctx: IContext): ts.VariableStatement => {
     const caller = () =>
       factory.createCallExpression(
@@ -70,7 +113,8 @@ export namespace NestiaMigrateApiSimulationProgrammer {
           ctx,
           ctx.route.parameters.length === 0 &&
             ctx.route.query === null &&
-            ctx.route.body === null
+            ctx.route.body === null &&
+            ctx.route.headers === null
             ? "_connection"
             : undefined,
         ),
@@ -127,6 +171,20 @@ export namespace NestiaMigrateApiSimulationProgrammer {
             },
           ]
         : []),
+      // the headers travel in the connection, validated as the server does
+      ...(ctx.route.headers
+        ? [
+            {
+              category: "headers",
+              name: ctx.route.headers.key,
+              schema: NestiaMigrateSchemaProgrammer.write({
+                components: ctx.components,
+                importer: ctx.importer,
+                schema: ctx.route.headers.schema,
+              }),
+            },
+          ]
+        : []),
     ];
     if (parameters.length === 0) return [];
 
@@ -206,7 +264,9 @@ export namespace NestiaMigrateApiSimulationProgrammer {
                   ),
                   "assert",
                 ),
-                undefined,
+                // `connection.headers` is typed optional with optional
+                // members, so the headers name their own type to be checked
+                p.category === "headers" ? [p.schema] : undefined,
                 [
                   p.category === "headers"
                     ? factory.createIdentifier("connection.headers")
@@ -218,78 +278,11 @@ export namespace NestiaMigrateApiSimulationProgrammer {
         ),
       )
       .map(factory.createExpressionStatement) as ts.Statement[];
-    return [validator, tryAndCatch(ctx.importer, individual)];
+    // the SDK fetches without propagation, so an invalid simulated request
+    // throws its HttpError as the real one does, instead of answering a
+    // propagation object in place of the response
+    return [validator, ...individual];
   };
-
-  const tryAndCatch = (
-    importer: NestiaMigrateImportProgrammer,
-    individual: ts.Statement[],
-  ) =>
-    factory.createTryStatement(
-      factory.createBlock(individual, true),
-      factory.createCatchClause(
-        "exp",
-        factory.createBlock(
-          [
-            factory.createIfStatement(
-              factory.createLogicalNot(
-                factory.createCallExpression(
-                  IdentifierFactory.access(
-                    factory.createIdentifier(
-                      importer.external({
-                        type: "default",
-                        library: "typia",
-                        name: "typia",
-                      }),
-                    ),
-                    "is",
-                  ),
-                  [
-                    factory.createTypeReferenceNode(
-                      importer.external({
-                        type: "instance",
-                        library: "@nestia/fetcher",
-                        name: "HttpError",
-                      }),
-                    ),
-                  ],
-                  [factory.createIdentifier("exp")],
-                ),
-              ),
-              factory.createThrowStatement(factory.createIdentifier("exp")),
-            ),
-            factory.createReturnStatement(
-              factory.createAsExpression(
-                factory.createObjectLiteralExpression(
-                  [
-                    factory.createPropertyAssignment(
-                      "success",
-                      factory.createFalse(),
-                    ),
-                    factory.createPropertyAssignment(
-                      "status",
-                      factory.createIdentifier("exp.status"),
-                    ),
-                    factory.createPropertyAssignment(
-                      "headers",
-                      factory.createIdentifier("exp.headers"),
-                    ),
-                    factory.createPropertyAssignment(
-                      "data",
-                      factory.createIdentifier("exp.toJSON().message"),
-                    ),
-                  ],
-                  true,
-                ),
-                TypeFactory.keyword("any"),
-              ),
-            ),
-          ],
-          true,
-        ),
-      ),
-      undefined,
-    );
 }
 
 const constant = (name: string, expression: ts.Expression) =>

package/src/programmers/NestiaMigrateApiStartProgrammer.ts

@@ -9,15 +9,31 @@ import { FilePrinter } from "../utils/FilePrinter";
 import { NestiaMigrateE2eFunctionProgrammer } from "./NestiaMigrateE2eFileProgrammer";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 
+/**
+ * Generates the `test/start.ts` of an SDK project: a small program that calls
+ * one API function.
+ *
+ * @evidence contracts/common.md#principled-implementation The program builds a connection from the global test settings and the first server of the document, adds the simulate flag when requested, and calls the first route the way the generated e2e tests do, so one command can check that the SDK and a server agree.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function and private helpers for the connection, the main function, and the starter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The route is the first one, so the same document always generates the same file.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateApiStartProgrammer {
+  /**
+   * Returns the `test/start.ts` file of an SDK project.
+   *
+   * @evidence contracts/common.md#principled-implementation The file imports what the body uses, defines `main`, and starts it, exiting with a failure status when it rejects.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The content derives from the document.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (
     context: INestiaMigrateContext,
   ): Record<string, string> => {
     const importer: NestiaMigrateImportProgrammer =
       new NestiaMigrateImportProgrammer();
-    const route: IHttpMigrateRoute | undefined = pick(
-      context.application.routes,
-    );
+    // the first route, so the same document always generates the same file
+    const route: IHttpMigrateRoute | undefined = context.application.routes[0];
     const main: ts.VariableStatement = writeMain(context, importer, route);
     const statements: ts.Statement[] = [
       ...importer.toStatements(
@@ -197,10 +213,3 @@ export namespace NestiaMigrateApiStartProgrammer {
       ],
     );
 }
-
-const pick = <T>(array: T[]): T | undefined => {
-  if (array.length === 0) return undefined;
-  const rand: number = Math.random() * array.length;
-  const index: number = Math.min(array.length - 1, Math.floor(rand));
-  return array[index]!;
-};

package/src/programmers/NestiaMigrateDtoProgrammer.ts

@@ -10,17 +10,50 @@ import { StringUtil } from "../utils/StringUtil";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the DTO type aliases from the component schemas.
+ *
+ * @evidence contracts/common.md#principled-implementation Each component name is normalized into a valid dotted name, the dots become nested namespaces, and each schema becomes an exported type alias with its description and its tags as a comment.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and private builders for the module tree and the alias.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The names derive from the schema names.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateDtoProgrammer {
+  /**
+   * A node of the DTO namespace tree: its name, its children, and the writer of
+   * its alias, or `null` for a namespace without a type of its own.
+   *
+   * @evidence contracts/common.md#principled-implementation The tree mirrors the dotted names of the schemas, so a namespace exists exactly when a name passes through it.
+   * @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 the meaning of each member.
+   */
   export interface IModule {
     name: string;
+
+    /** Child segments of qualified schema names, preserving insertion order. */
     children: Map<string, IModule>;
+
+    /** Alias writer for a schema at this node, or null for a namespace alone. */
     programmer:
       | null
       | ((importer: NestiaMigrateImportProgrammer) => ts.TypeAliasDeclaration);
   }
 
+  /**
+   * Returns the root of the DTO tree: a map from the first name segment to its
+   * module.
+   *
+   * @evidence contracts/common.md#principled-implementation Each schema key is split on slashes, its segments are escaped into valid identifiers and joined, and the result is inserted along its dotted path.
+   * @evidence contracts/common.md#clear-and-simple-design One function over one insertion helper.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names come from the document.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const compose = (props: {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
   }): Map<string, IModule> => {
     const dict: Map<string, IModule> = new Map();

package/src/programmers/NestiaMigrateE2eFileProgrammer.ts

@@ -9,14 +9,47 @@ import { INestiaMigrateConfig } from "../structures/INestiaMigrateConfig";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 import { NestiaMigrateSchemaProgrammer } from "./NestiaMigrateSchemaProgrammer";
 
+/**
+ * Generates the e2e test function of one route.
+ *
+ * @evidence contracts/common.md#principled-implementation The function calls the route through the SDK with random arguments made by `typia.random`, including generated headers, and asserts the response with `typia.assert`, so the test checks that the server's answer matches the declared type.
+ * @evidence contracts/common.md#clear-and-simple-design One entry function, one public body writer shared with the start programmer, and a private call writer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The arguments are drawn at run time, and no route is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateE2eFunctionProgrammer {
+  /**
+   * The input of one test function: the configuration, the components, the
+   * importer, and the route.
+   *
+   * @evidence contracts/common.md#principled-implementation The record holds exactly what the generation needs.
+   * @evidence contracts/common.md#clear-and-simple-design A flat record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment lists the fields.
+   */
   export interface IContext {
+    /** Calling convention and optional generated features for this operation. */
     config: INestiaMigrateConfig;
+
+    /** Component schemas used to resolve DTO references. */
     components: OpenApi.IComponents;
+
+    /** File-local import collector shared with the surrounding file writer. */
     importer: NestiaMigrateImportProgrammer;
+
+    /** Analyzed operation, with the accessor chosen for this generation. */
     route: IHttpMigrateRoute;
   }
 
+  /**
+   * Returns the exported async test function of a route, named `test_api_`
+   * followed by its accessor.
+   *
+   * @evidence contracts/common.md#principled-implementation The name joins `test`, `api`, and the accessor with underscores, so it is unique for a route and matches the prefix that the e2e executor discovers.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The name derives from the accessor.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the naming rule.
+   */
   export const write = (ctx: IContext): ts.FunctionDeclaration =>
     factory.createFunctionDeclaration(
       [
@@ -47,6 +80,15 @@ export namespace NestiaMigrateE2eFunctionProgrammer {
       factory.createBlock(writeBody(ctx), true),
     );
 
+  /**
+   * Returns the statements of the test body: the call with random arguments and
+   * the type assertion of its output.
+   *
+   * @evidence contracts/common.md#principled-implementation The call expression follows the parameter mode of the configuration, and the output is typed by the response schema when there is one.
+   * @evidence contracts/common.md#clear-and-simple-design One function shared with the start programmer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The body follows the route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const writeBody = (ctx: IContext): ts.Statement[] => [
     factory.createVariableStatement(
       [],
@@ -91,14 +133,6 @@ export namespace NestiaMigrateE2eFunctionProgrammer {
       factory.createIdentifier("api.functional"),
       factory.createIdentifier(ctx.route.accessor.join(".")),
     );
-    const connection = factory.createIdentifier("connection");
-    if (
-      ctx.route.parameters.length === 0 &&
-      ctx.route.query === null &&
-      ctx.route.body === null
-    )
-      return factory.createCallExpression(fetch, undefined, [connection]);
-
     const random = factory.createPropertyAccessExpression(
       factory.createIdentifier(
         ctx.importer.external({
@@ -109,6 +143,47 @@ export namespace NestiaMigrateE2eFunctionProgrammer {
       ),
       "random",
     );
+    // the route's headers travel in the connection, as the server requires
+    const connection: ts.Expression = ctx.route.headers
+      ? factory.createObjectLiteralExpression(
+          [
+            factory.createSpreadAssignment(
+              factory.createIdentifier("connection"),
+            ),
+            factory.createPropertyAssignment(
+              "headers",
+              factory.createObjectLiteralExpression(
+                [
+                  factory.createSpreadAssignment(
+                    factory.createIdentifier("connection.headers"),
+                  ),
+                  factory.createSpreadAssignment(
+                    factory.createCallExpression(
+                      random,
+                      [
+                        NestiaMigrateSchemaProgrammer.write({
+                          components: ctx.components,
+                          importer: ctx.importer,
+                          schema: ctx.route.headers.schema,
+                        }),
+                      ],
+                      undefined,
+                    ),
+                  ),
+                ],
+                true,
+              ),
+            ),
+          ],
+          true,
+        )
+      : factory.createIdentifier("connection");
+    if (
+      ctx.route.parameters.length === 0 &&
+      ctx.route.query === null &&
+      ctx.route.body === null
+    )
+      return factory.createCallExpression(fetch, undefined, [connection]);
     if (ctx.config.keyword === true)
       return factory.createCallExpression(fetch, undefined, [
         connection,

package/src/programmers/NestiaMigrateE2eProgrammer.ts

@@ -8,7 +8,23 @@ import { FilePrinter } from "../utils/FilePrinter";
 import { NestiaMigrateE2eFunctionProgrammer } from "./NestiaMigrateE2eFileProgrammer";
 import { NestiaMigrateImportProgrammer } from "./NestiaMigrateImportProgrammer";
 
+/**
+ * Generates the e2e test files, one per route.
+ *
+ * @evidence contracts/common.md#principled-implementation Each route becomes a file whose path depends on the mode and whose imports are resolved through the package name for a monorepo and through the built library path otherwise.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and one private file writer.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The layout follows the accessors.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what is generated.
+ */
 export namespace NestiaMigrateE2eProgrammer {
+  /**
+   * Returns the map from file path to content of the e2e tests.
+   *
+   * @evidence contracts/common.md#principled-implementation The file name is `test_api_` plus the accessor, so each route has exactly one file.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The names follow the accessors.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the result.
+   */
   export const write = (ctx: INestiaMigrateContext): Record<string, string> =>
     Object.fromEntries(
       ctx.application.routes