@nestia/sdk 14.0.1 → 14.0.3

package/src/factories/IdentifierFactory.ts

@@ -19,11 +19,23 @@ 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 choose an identifier or a string literal by the syntax of the name, so any string can be a key.
+ * @evidence contracts/common.md#clear-and-simple-design Three functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The identifier test is inlined and conservative.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation IdentifierFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 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, and a valid name outside the conservative pattern becomes an equivalent quoted key.
+   * @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.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IdentifierFactory.identifier constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const identifier = (name: string): Identifier | StringLiteral =>
     isVariableName(name)
@@ -33,6 +45,12 @@ 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 key becomes a property when it is an identifier and an element access otherwise.
+   * @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.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IdentifierFactory.access constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const access = (
     input: Expression,
@@ -60,6 +78,12 @@ 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 The question token becomes the optional marker and any other initializer is passed through.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the declaration grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the optional marker.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation IdentifierFactory.parameter constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
    */
   export const parameter = (
     name: string | Identifier,

package/src/factories/LiteralFactory.ts

@@ -15,16 +15,43 @@ const isNode = (value: unknown): value is Expression =>
   typeof (value as { kind?: unknown }).kind === "string";
 
 /**
- * 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.
+ * Recursive value-to-AST-literal builder. Arrow-function, call-expression and
+ * identifier nodes pass through only when the caller explicitly requests
+ * expression preservation. Ordinary values may contain the same `kind` names.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace maps values to literal nodes by type.
+ * @evidence contracts/common.md#clear-and-simple-design One function and two helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The mapping is by type.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation LiteralFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace LiteralFactory {
-  export const write = (input: any): Expression => {
+  /**
+   * Builds the expression of a value; arrow function, call, and identifier
+   * nodes pass through when `preserveExpressions` is true. Functions become
+   * `undefined`; other unsupported types throw, and object properties whose
+   * values are undefined are omitted.
+   *
+   * @evidence contracts/common.md#principled-implementation The value is dispatched by type in a fixed order and containers are written element by element.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The dispatch is general.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the mapping.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation LiteralFactory.write constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  export const write = (
+    input: any,
+    preserveExpressions = false,
+  ): Expression => {
     if (input === null) return factory.createNull();
-    if (isNode(input) && PASSTHROUGH_KINDS.has(input.kind)) return input;
-    if (Array.isArray(input)) return writeArray(input);
-    if (typeof input === "object") return writeObject(input as object);
+    if (
+      preserveExpressions &&
+      isNode(input) &&
+      PASSTHROUGH_KINDS.has(input.kind)
+    )
+      return input;
+    if (Array.isArray(input)) return writeArray(input, preserveExpressions);
+    if (typeof input === "object")
+      return writeObject(input as object, preserveExpressions);
     if (typeof input === "boolean")
       return input ? factory.createTrue() : factory.createFalse();
     if (typeof input === "number") return ExpressionFactory.number(input);
@@ -41,19 +68,25 @@ export namespace LiteralFactory {
     throw new TypeError("LiteralFactory.write: unsupported input type.");
   };
 
-  const writeObject = (obj: object): Expression =>
+  const writeObject = (obj: object, preserveExpressions: boolean): Expression =>
     factory.createObjectLiteralExpression(
       Object.entries(obj)
         .filter(([, value]) => value !== undefined)
         .map(([key, value]) =>
           factory.createPropertyAssignment(
             IdentifierFactory.identifier(key),
-            write(value),
+            write(value, preserveExpressions),
           ),
         ),
       true,
     );
 
-  const writeArray = (array: readonly any[]): Expression =>
-    factory.createArrayLiteralExpression(array.map(write), true);
+  const writeArray = (
+    array: readonly any[],
+    preserveExpressions: boolean,
+  ): Expression =>
+    factory.createArrayLiteralExpression(
+      array.map((value) => write(value, preserveExpressions)),
+      true,
+    );
 }

package/src/factories/StatementFactory.ts

@@ -8,8 +8,26 @@ 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.
+ * @evidence contracts/common.md#clear-and-simple-design Two functions, one for let and one for const.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It only builds nodes.
+ * @evidence contracts/common.md#meaningful-documentation The comment states its purpose.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation StatementFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace StatementFactory {
+  /**
+   * Builds a `let` statement; without a type and an initializer it is typed
+   * `any`.
+   *
+   * @evidence contracts/common.md#principled-implementation A declaration without either would be implicitly any, so the type is stated.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the default type.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation StatementFactory.mut constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const mut = (props: {
     name: string;
     type?: TypeNode | undefined;
@@ -34,6 +52,15 @@ export namespace StatementFactory {
       ),
     );
 
+  /**
+   * Builds a `const` statement from a name, a type, and a 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 grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states its inputs.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation StatementFactory.constant constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const constant = (props: {
     name: string;
     type?: TypeNode | undefined;

package/src/factories/TypeFactory.ts

@@ -6,6 +6,12 @@ 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 names to the keyword 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.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation TypeFactory constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
  */
 export namespace TypeFactory {
   const KEYWORDS = {
@@ -20,8 +26,26 @@ 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, so a 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.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation TypeFactory.Keyword is the key union of the syntax-kind table and defines no native path conversion or process boundary.
+   */
   export type Keyword = keyof typeof KEYWORDS;
 
+  /**
+   * Builds the keyword type node of a name.
+   *
+   * @evidence contracts/common.md#principled-implementation The name is looked up in the table.
+   * @evidence contracts/common.md#clear-and-simple-design One lookup.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It follows the grammar.
+   * @evidence contracts/common.md#meaningful-documentation The comment states its input.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation TypeFactory.keyword constructs TypeScript syntax nodes; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const keyword = (type: Keyword): KeywordTypeNode =>
     factory.createKeywordTypeNode(KEYWORDS[type]);
 }

package/src/generates/CloneGenerator.ts

@@ -15,17 +15,38 @@ import { SdkHttpCloneProgrammer } from "./internal/SdkHttpCloneProgrammer";
 import { SdkHttpCloneReferencer } from "./internal/SdkHttpCloneReferencer";
 import { SdkWebSocketCloneProgrammer } from "./internal/SdkWebSocketCloneProgrammer";
 
+/**
+ * Writes the DTO declarations of the SDK: the `structures` files that the
+ * functions import when `clone` is on.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace composes the declarations from the analyzed types, rewrites the routes to reference them, and prints one file per top-level module.
+ * @evidence contracts/common.md#clear-and-simple-design One public function with two private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Every declaration goes through the shared printer, and no type is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation The writer passes native output locations to Node fs and FilePrinter; module specifiers are produced separately by ImportDictionary. The structures suffix uses forward slashes, which Node accepts on Windows and POSIX, without treating spelling as canonical file identity.
+ */
 export namespace CloneGenerator {
+  /**
+   * Writes the `structures` directory of the SDK output.
+   *
+   * Structural route references are updated even when every JSON DTO is inline
+   * and no structure file is needed. WebSocket source cloning stays separate.
+   *
+   * @evidence contracts/common.md#principled-implementation HTTP and MCP JSON declarations share the analyzed collection; WebSocket sources are copied separately. Route references are updated even for inline-only graphs, then named modules are written sequentially so a failure stops at the first file.
+   * @evidence contracts/common.md#clear-and-simple-design One function over the two programmers, the referencer, and the file writer.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The directory is created recursively and its failure is not swallowed.
+   * @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 the output structures directory and FilePrinter writes generated declarations; WebSocket source lookup and copying remain delegated to its source-cloning owner. Filesystem errors propagate rather than being translated into platform-specific shell commands.
+   */
   export const write = async (app: ITypedApplication): Promise<void> => {
     const dict: Map<string, SdkHttpCloneProgrammer.IModule> =
       SdkHttpCloneProgrammer.write(app);
     const websocket: Set<string> = await SdkWebSocketCloneProgrammer.write(app);
-    if (dict.size === 0 && websocket.size === 0) return;
-
     SdkHttpCloneReferencer.replace(app, websocket);
-    try {
-      await fs.promises.mkdir(`${app.project.config.output}/structures`);
-    } catch {}
+    if (dict.size === 0 && websocket.size === 0) return;
+    await fs.promises.mkdir(`${app.project.config.output}/structures`, {
+      recursive: true,
+    });
     for (const [key, value] of dict)
       await writeDtoFile(app.project)(key, value);
   };

package/src/generates/E2eGenerator.ts

@@ -4,7 +4,26 @@ import path from "path";
 import { ITypedApplication } from "../structures/ITypedApplication";
 import { E2eFileProgrammer } from "./internal/E2eFileProgrammer";
 
+/**
+ * Writes the e2e test functions of the SDK.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace creates the output directories and writes one test file per HTTP route.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and one directory helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Only HTTP routes have a test, and no route is skipped by name.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation The output root is resolved with Node path.resolve, descendants use path.join and recursive fs.mkdir creates them. SDK import paths are passed to E2eFileProgrammer independently from native directory paths.
+ */
 export namespace E2eGenerator {
+  /**
+   * Writes one test function per HTTP route under `features/api/automated` of
+   * the e2e output directory, creating the directories as needed.
+   *
+   * @evidence contracts/common.md#principled-implementation The directories are created recursively, so an existing tree is reused, and each route's file is written in sequence.
+   * @evidence contracts/common.md#clear-and-simple-design One loop over the routes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts WebSocket and MCP routes are not tests of the HTTP SDK and are left out by protocol.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation Native output and SDK roots use path.resolve and path.join before mkdir or file generation. No shell or filesystem case assumption participates; the generated HTTP route names have already passed accessor analysis.
+   */
   export const generate = async (app: ITypedApplication): Promise<void> => {
     console.log("Generating E2E Test Functions");
 

package/src/generates/SdkGenerator.ts

@@ -1,5 +1,4 @@
 import fs from "fs";
-import NodePath from "path";
 
 import { INestiaConfig } from "../INestiaConfig";
 import { IReflectOperationError } from "../structures/IReflectOperationError";
@@ -7,13 +6,34 @@ import { IReflectType } from "../structures/IReflectType";
 import { ITypedApplication } from "../structures/ITypedApplication";
 import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
 import { ITypedMcpRoute } from "../structures/ITypedMcpRoute";
+import { SDK_BUNDLE_PATH } from "../utils/SdkBundlePath";
 import { StringUtil } from "../utils/StringUtil";
 import { CloneGenerator } from "./CloneGenerator";
 import { SdkDistributionComposer } from "./internal/SdkDistributionComposer";
 import { SdkFileProgrammer } from "./internal/SdkFileProgrammer";
 import { SdkHttpParameterProgrammer } from "./internal/SdkHttpParameterProgrammer";
 
+/**
+ * Generates the SDK library and validates the analyzed routes it needs.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace bundles the static files, writes the DTOs and the functions, composes the distribution package, and reports the errors the generation would meet.
+ * @evidence contracts/common.md#clear-and-simple-design Two public functions, one public constant, and the private validators.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Validation and generation share the same route model.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Static bundle enumeration and output creation use Node fs; declaration/module path conversion and distribution process launching are delegated to ImportDictionary and SdkDistributionComposer. Existing file spelling is checked by the filesystem rather than an OS-name case rule.
+ */
 export namespace SdkGenerator {
+  /**
+   * Writes the SDK into the configured output directory: the bundled files, the
+   * DTOs when `clone` is on, the functions, and the distribution package when
+   * `distribute` is set.
+   *
+   * @evidence contracts/common.md#principled-implementation The steps run in dependency order, the bundle first and the distribution last. An absent output option throws before writing; a configured directory that does not exist is created recursively.
+   * @evidence contracts/common.md#clear-and-simple-design One function that delegates each step.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The steps are sequential and each awaits the previous one.
+   * @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 and the bundle writer accept the configured native output path; subsequent file and process boundaries belong to their delegated writers. Configuration omission is distinct from a missing on-disk directory.
+   */
   export const generate = async (app: ITypedApplication): Promise<void> => {
     if (app.project.config.output === undefined)
       throw new Error("Output directory is not defined.");
@@ -40,6 +60,18 @@ export namespace SdkGenerator {
       });
   };
 
+  /**
+   * Returns the errors of routes that cannot become an SDK: MCP tools with
+   * duplicate names or accessors, and, without `clone`, HTTP routes whose
+   * parameter or return types are implicit, plus implicit exception types when
+   * propagation is enabled.
+   *
+   * @evidence contracts/common.md#principled-implementation The MCP checks always apply, and the implicit return check applies only where the SDK would have to name the type, because `clone` writes it as a declaration instead.
+   * @evidence contracts/common.md#clear-and-simple-design One function over three checks.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The list is collected, not thrown, so one run reports every error.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation Validation judges analyzed route types and names and performs no native filesystem or process operation.
+   */
   export const validate = (
     app: ITypedApplication,
   ): IReflectOperationError[] => {
@@ -162,6 +194,12 @@ export namespace SdkGenerator {
    * Files the user already has are never touched, so that hand-written
    * customizations (e.g. extra re-exports in `module.ts`) survive regeneration.
    * Only missing files are filled in from the bundle.
+   *
+   * @evidence contracts/common.md#principled-implementation A file that the user has customized is never overwritten, and only files that are missing are filled in from the bundle.
+   * @evidence contracts/common.md#clear-and-simple-design One loop with two guards.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The existing target is checked before the write.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation fs.readdir/stat enumerate the installed bundle and fs.existsSync checks each target under the filesystem's own policy before writing UTF-8. Forward slash suffixes are accepted by Node on supported native platforms; concurrent generation into the same output is not an exclusive ownership guarantee.
    */
   export const bundle = async (output: string): Promise<void> => {
     const files: string[] = await fs.promises.readdir(BUNDLE_PATH);
@@ -177,12 +215,5 @@ export namespace SdkGenerator {
     }
   };
 
-  export const BUNDLE_PATH = NodePath.join(
-    __dirname,
-    "..",
-    "..",
-    "assets",
-    "bundle",
-    "api",
-  );
+  export const BUNDLE_PATH = SDK_BUNDLE_PATH;
 }

package/src/generates/SwaggerGenerator.ts

@@ -24,9 +24,29 @@ import { ITypedHttpRoute } from "../structures/ITypedHttpRoute";
 import { FileRetriever } from "../utils/FileRetriever";
 import { SdkHttpParameterProgrammer } from "./internal/SdkHttpParameterProgrammer";
 import { SwaggerOperationComposer } from "./internal/SwaggerOperationComposer";
-import { SwaggerReadonlyArrayEmender } from "./internal/SwaggerReadonlyArrayEmender";
 
+/**
+ * Composes and writes the OpenAPI document.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace resolves the output location, builds the document from the routes, downgrades it when an older version is configured, and writes it.
+ * @evidence contracts/common.md#clear-and-simple-design Three public functions and private helpers for security, customizers, and the copy of the document.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The composition never edits data it does not own.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Output locations use Node path.parse/resolve/join and UTF-8 fs writes; package defaults are located through FileRetriever from the current native working directory. HTTP operation paths remain protocol strings handled by PathAnalyzer.
+ */
 export namespace SwaggerGenerator {
+  /**
+   * Writes the document to the configured location: a `.json` path as it is,
+   * and a directory as its `swagger.json`.
+   *
+   * The document is downgraded when `openapi` names an older version.
+   *
+   * @evidence contracts/common.md#principled-implementation The directory is created recursively and a failure to create it is reported with its cause; the document is composed, converted, and written in that order.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The failure to create the directory is not swallowed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation path.parse classifies an output by its extension, path.resolve and path.dirname obtain native destinations, and fs.mkdir/writeFile own creation and writing without shell interpretation. Any nonempty extension denotes a file; the example .json extension is not an exclusive suffix check.
+   */
   export const generate = async (app: ITypedApplication): Promise<void> => {
     // GET CONFIGURATION
     console.log("Generating Swagger Document");
@@ -40,14 +60,15 @@ export namespace SwaggerGenerator {
       ? path.resolve(config.output)
       : path.join(path.resolve(config.output), "swagger.json");
     const directory: string = path.dirname(location);
-    if (fs.existsSync(directory) === false)
-      try {
-        await fs.promises.mkdir(directory, { recursive: true });
-      } catch {}
-    if (fs.existsSync(directory) === false)
+    try {
+      await fs.promises.mkdir(directory, { recursive: true });
+    } catch (error) {
       throw new Error(
-        `Error on NestiaApplication.swagger(): failed to create output directory: ${directory}`,
+        `Error on NestiaApplication.swagger(): failed to create output directory: ${directory} (${
+          error instanceof Error ? error.message : String(error)
+        })`,
       );
+    }
     // COMPOSE SWAGGER DOCUMENT
     const document: OpenApi.IDocument = compose({
       config,
@@ -76,6 +97,19 @@ export namespace SwaggerGenerator {
     );
   };
 
+  /**
+   * Composes the document of the HTTP routes into the given document: the
+   * components of every schema, and the paths.
+   *
+   * A route tagged `@internal` or `@hidden`, or excluded by
+   * `@ApiExcludeEndpoint`, is left out.
+   *
+   * @evidence contracts/common.md#principled-implementation The schemas of all routes are composed in one call, so a component shared by routes exists once, and the readonly arrays are emended before the paths refer to them.
+   * @evidence contracts/common.md#clear-and-simple-design One function of sequential steps.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The exclusion is the documented set of tags and decorators.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation compose operates on analyzed metadata and OpenAPI protocol paths; it neither opens native files nor launches processes.
+   */
   export const compose = (props: {
     config: Omit<INestiaConfig.ISwaggerConfig, "output">;
     routes: ITypedHttpRoute[];
@@ -102,13 +136,6 @@ export namespace SwaggerGenerator {
       version: "3.1",
       metadatas,
     });
-    json.schemas.forEach((schema, i) =>
-      SwaggerReadonlyArrayEmender.emend({
-        components: json.components,
-        schema,
-        metadata: metadatas[i]!,
-      }),
-    );
     const dict: WeakMap<MetadataSchema, OpenApi.IJsonSchema> = new WeakMap();
     json.schemas.forEach((schema, i) => dict.set(metadatas[i]!, schema));
     const schema = (
@@ -128,6 +155,21 @@ export namespace SwaggerGenerator {
     return document;
   };
 
+  /**
+   * Returns the document the composition starts from: the configured info,
+   * servers, security schemes, and tags, or the defaults.
+   *
+   * Tags are copied immediately; configured servers, security schemes and
+   * nested info values remain shared until compose detaches the document before
+   * customizers run. Callers using initialize alone must preserve those shared
+   * values.
+   *
+   * @evidence contracts/common.md#principled-implementation A per-call lazy Singleton reads package metadata at most once when info defaults need it. Each call allocates a document and copies the tag list; configured servers, security schemes and nested info values are detached later by compose before customization.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The defaults follow the configuration contract; initialize does not mutate configured values, while compose owns detaching the remaining shared JSON trees.
+   * @evidence contracts/common.md#meaningful-documentation The comment identifies defaults and distinguishes the immediate tag copy from values shared until compose, including the restriction on initialize-only callers.
+   * @evidence contracts/portability.md#os-neutral-implementation The lazy package-info reader starts from process.cwd and FileRetriever supplies the nearest package.json within its bounded native-parent search. fs.readFile reads UTF-8; unreadable or malformed package metadata yields documented info defaults rather than an OS-specific fallback command.
+   */
   export const initialize = async (
     config: Omit<INestiaConfig.ISwaggerConfig, "output">,
   ): Promise<OpenApi.IDocument> => {

package/src/generates/internal/E2eFileProgrammer.ts

@@ -17,7 +17,26 @@ import { SdkAliasCollection } from "./SdkAliasCollection";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkImportWizard } from "./SdkImportWizard";
 
+/**
+ * Writes the e2e test file of one HTTP route.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace prints an exported function that calls the route's SDK function with random arguments and asserts its result.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The generated file uses the SDK the same way a user does.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation The caller supplies native api/current locations; ImportDictionary converts relative imports to slash-separated language specifiers, and FilePrinter writes the computed test pathname through Node fs with UTF-8. No filename case policy is inferred.
+ */
 export namespace E2eFileProgrammer {
+  /**
+   * Writes the test file of a route, named after its accessor, with the imports
+   * it needs.
+   *
+   * @evidence contracts/common.md#principled-implementation The imports are collected while the function is built and printed before it.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The file name is derived from the route accessor.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation The caller supplies native api/current locations; ImportDictionary converts relative imports to slash-separated language specifiers, and FilePrinter writes the computed test pathname through Node fs with UTF-8. No filename case policy is inferred.
+   */
   export const generate =
     (project: INestiaProject) =>
     (props: { api: string; current: string }) =>
@@ -142,6 +161,7 @@ export namespace E2eFileProgrammer {
                       ),
                     ]),
                   ),
+                  true,
                 ),
               ]
             : entries.map((e) =>

package/src/generates/internal/FilePrinter.ts

@@ -9,7 +9,26 @@ import {
 import fs from "fs";
 import { format } from "prettier";
 
+/**
+ * Prints generated syntax trees to files.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace attaches comments, writes tags, prints statements, and formats the result.
+ * @evidence contracts/common.md#clear-and-simple-design Four functions and one private formatter.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Formatting failure keeps the unformatted script.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidence contracts/portability.md#os-neutral-implementation Only write crosses the native filesystem boundary, through fs.promises.writeFile with the caller's location and UTF-8. The other helpers construct language comments and syntax independently of native path identity or separators.
+ */
 export namespace FilePrinter {
+  /**
+   * Attaches a comment to a node as a JSDoc block, escaping every comment
+   * terminator in it so the comment cannot end early.
+   *
+   * @evidence contracts/common.md#principled-implementation Each line of the comment becomes one JSDoc line and an empty comment adds nothing.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The closing marker is escaped rather than dropped.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation description attaches language-level comment text to an AST and performs no native filesystem or process operation.
+   */
   export const description = <T extends Node>(node: T, comment: string): T => {
     if (comment.length === 0) return node;
     return addSyntheticLeadingComment(
@@ -43,6 +62,11 @@ export namespace FilePrinter {
    *
    * @param head The tag's name, followed by a `@param` tag's parameter name
    * @param text The tag's text
+   * @evidence contracts/common.md#principled-implementation The margin is the width of the head, and a text whose first line is indented starts on the next line.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Every line keeps the indentation it has beyond the margin.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation jsDocTag formats TypeScript comment text; indentation and line feeds express language syntax rather than native paths or handles.
    */
   export const jsDocTag = (head: string, text: string): string => {
     const lines: string[] = text.split("\n").map((line) => line.trimEnd());
@@ -59,9 +83,28 @@ export namespace FilePrinter {
     ].join("\n");
   };
 
+  /**
+   * Returns a statement that prints as an empty line.
+   *
+   * @evidence contracts/common.md#principled-implementation A line break is an identifier statement, which the printer emits between its neighbors.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The printer places the break where it is used.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation enter returns a language AST node and owns no filesystem or process boundary.
+   */
   export const enter = () =>
     factory.createExpressionStatement(factory.createIdentifier("\n"));
 
+  /**
+   * Prints the statements to the location, prefixed by the optional top text,
+   * and formats the script.
+   *
+   * @evidence contracts/common.md#principled-implementation The script is formatted with Prettier, and the unformatted script is written when the formatter throws, so a formatting failure never loses the file.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The write is awaited and its failure is thrown.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidence contracts/portability.md#os-neutral-implementation writeFile receives the native pathname as a separate argument and writes UTF-8 after formatting. Its caller owns parent-directory creation; write failures propagate on every platform without shell quoting or separator rewriting.
+   */
   export const write = async (props: {
     location: string;
     statements: Node[];