@nestia/sdk 14.0.0 → 14.0.2

package/README.md

@@ -60,7 +60,7 @@ Check out the document in the [website](https://nestia.io/docs/):
 ### 🏠 Home
   - [Introduction](https://nestia.io/docs/)
   - [Setup](https://nestia.io/docs/setup/)
-  - [Pure TypeScript](https://nestia.io/docs/pure)
+  - [Pure TypeScript](https://nestia.io/docs/core/TypedBody/)
 
 ### 📖 Features
   - Core Library

package/assets/bundle/distribute/build-sdk.cjs

@@ -0,0 +1,28 @@
+const cp = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+// Resolve the generated package's data against its own location, so invoking
+// the build from another directory cannot redirect deletion or generation.
+const { nestia } = require("./package.json");
+const root = path.resolve(__dirname, nestia.root);
+const output = path.resolve(__dirname, nestia.output);
+fs.rmSync(path.join(output, "functional"), { recursive: true, force: true });
+
+const args = ["nestia", "sdk"];
+if (process.platform !== "win32")
+  cp.execFileSync("npx", args, { cwd: root, stdio: "inherit" });
+else {
+  // Node cannot start a .cmd shim directly. The npm installation beside the
+  // shim provides the same entry point without interpreting a shell string.
+  const directory = (process.env.PATH ?? "")
+    .split(path.delimiter)
+    .find((entry) => fs.existsSync(path.join(entry, "npx.cmd")));
+  const cli = directory === undefined ? undefined : [
+    path.join(directory, "node_modules/npm/bin/npx-cli.js"),
+    path.resolve(directory, "../npm/bin/npx-cli.js"),
+  ].find((entry) => fs.existsSync(entry));
+  if (cli === undefined)
+    throw new Error("Unable to locate npx's JavaScript entry point beside npx.cmd on PATH.");
+  cp.execFileSync(process.execPath, [cli, ...args], { cwd: root, stdio: "inherit" });
+}

package/assets/bundle/distribute/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ORGANIZATION/PROJECT-api",
-  "version": "14.0.0",
+  "version": "14.0.2",
   "description": "SDK library generated by Nestia",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "scripts": {
     "build": "npm run build:sdk && npm run compile",
-    "build:sdk": "rimraf ${output}/functional && cd ${root} && npx nestia sdk && cd ${current}",
-    "compile": "rimraf lib && tsc",
+    "build:sdk": "node build-sdk.cjs",
+    "compile": "rimraf lib && ttsc",
     "deploy": "npm run build && npm publish"
   },
   "repository": {
@@ -20,6 +20,10 @@
     "url": "https://github.com/samchon/nestia/issues"
   },
   "homepage": "https://nestia.io",
+  "nestia": {
+    "root": "${root}",
+    "output": "${output}"
+  },
   "files": [
     "lib",
     "package.json",

package/assets/bundle/distribute/tsconfig.json

@@ -1,109 +1,19 @@
 {
   "compilerOptions": {
-    /* Visit https://aka.ms/tsconfig to read more about this file */
-
-    /* Projects */
-    // "incremental": true,                              /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
-    // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
-    // "tsBuildInfoFile": "./.tsbuildinfo",              /* Specify the path to .tsbuildinfo incremental compilation file. */
-    // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects. */
-    // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
-    // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
-
-    /* Language and Environment */
-    "target": "ES5",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
-    "lib": [
-      "DOM",
-      "ES2015"
-    ],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
-    // "jsx": "preserve",                                /* Specify what JSX code is generated. */
-    // "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */
-    // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
-    // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
-    // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
-    // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
-    // "reactNamespace": "",                             /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
-    // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
-    // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
-    // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
-
-    /* Modules */
-    "module": "commonjs",                                /* Specify what module code is generated. */
-    // "rootDir": "./",                                  /* Specify the root folder within your source files. */
-    // "moduleResolution": "node",                       /* Specify how TypeScript looks up a file from a given module specifier. */
-    // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
-    // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
-    // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
-    // "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
-    // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
-    // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
-    // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
-    // "resolveJsonModule": true,                        /* Enable importing .json files. */
-    // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
-
-    /* JavaScript Support */
-    // "allowJs": true,                                  /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
-    // "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
-    // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
-
-    /* Emit */
-    "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
-    // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
-    // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
-    "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
-    // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
-    "outDir": "./lib",                                   /* Specify an output folder for all emitted files. */
-    // "removeComments": true,                           /* Disable emitting comments. */
-    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
-    // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
-    // "importsNotUsedAsValues": "remove",               /* Specify emit/checking behavior for imports that are only used for types. */
-    "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
-    // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
-    // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
-    // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
-    // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
-    // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
-    "newLine": "lf",                                /* Set the newline character for emitting files. */
-    // "stripInternal": true,                            /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
-    // "noEmitHelpers": true,                            /* Disable generating custom helper functions like '__extends' in compiled output. */
-    // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
-    // "preserveConstEnums": true,                       /* Disable erasing 'const enum' declarations in generated code. */
-    // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
-    // "preserveValueImports": true,                     /* Preserve unused imported values in the JavaScript output that would otherwise be removed. */
-
-    /* Interop Constraints */
-    // "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
-    // "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
-    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
-    // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
-    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
-
-    /* Type Checking */
-    "strict": true,                                      /* Enable all strict type-checking options. */
-    // "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied 'any' type. */
-    // "strictNullChecks": true,                         /* When type checking, take into account 'null' and 'undefined'. */
-    // "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
-    // "strictBindCallApply": true,                      /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
-    // "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
-    // "noImplicitThis": true,                           /* Enable error reporting when 'this' is given the type 'any'. */
-    // "useUnknownInCatchVariables": true,               /* Default catch clause variables as 'unknown' instead of 'any'. */
-    // "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
-    // "noUnusedLocals": true,                           /* Enable error reporting when local variables aren't read. */
-    // "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read. */
-    // "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
-    // "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
-    // "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
-    // "noUncheckedIndexedAccess": true,                 /* Add 'undefined' to a type when accessed using an index. */
-    // "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
-    // "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type. */
-    // "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
-    // "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
-
-    /* Completeness */
-    // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
-    "skipLibCheck": true,                                 /* Skip type checking all .d.ts files. */
+    "target": "ESNext",
+    "lib": ["DOM", "ESNext"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "rootDir": "${output}",
+    "types": ["*"],
+    "declaration": true,
+    "sourceMap": true,
+    "outDir": "./lib",
+    "newLine": "lf",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true
   },
-  "include": [
-    "${output}"
-  ]
+  "include": ["${output}"]
 }

package/lib/INestiaConfig.d.ts

@@ -4,6 +4,11 @@ import type { OpenApi } from "typia";
  * Definition for the `nestia.config.ts` file.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @evidence contracts/common.md#principled-implementation The input names the controllers to analyze and every optional property enables or refines one output (SDK, distribution, e2e, Swagger), so one configuration file drives every generator.
+ * @evidence contracts/common.md#clear-and-simple-design A flat record whose nested types describe the input and the Swagger options.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+ * @evidence contracts/common.md#meaningful-documentation Every property documents its meaning and default, which are the public contract of the configuration file.
+ * @evidence contracts/portability.md#os-neutral-implementation Source inputs and output/distribution/e2e destinations carry native pathname strings interpreted by their owning Node filesystem operations; the application callback bypasses source compilation. Swagger route paths are distinct protocol values, not native file identities.
  */
 export interface INestiaConfig {
     /**
@@ -40,10 +45,15 @@ export interface INestiaConfig {
      * Recommend to use `"packages/api"` value.
      */
     distribute?: string;
-    /** @default false */
+    /**
+     * Groups HTTP and WebSocket SDK call arguments in one props object after the
+     * connection. MCP wrappers retain their client and arguments parameters.
+     *
+     * @default false
+     */
     keyword?: boolean;
     /**
-     * Allow simulation mode.
+     * Allow simulation mode for HTTP SDK calls.
      *
      * If you configure this property to be `true`, the SDK library would be
      * contain simulation mode. In the simulation mode, the SDK library would not
@@ -61,7 +71,8 @@ export interface INestiaConfig {
      *
      * If you configure this property and runs `npx nestia e2e` command,
      * `@nestia/sdk` will analyze your NestJS backend server code, and generates
-     * e2e test functions for every API endpoints.
+     * e2e test functions for the analyzed HTTP endpoints. WebSocket and MCP
+     * operations have no generated HTTP test function.
      *
      * If not configured, you can't run `npx nestia e2e` command.
      */
@@ -70,10 +81,10 @@ export interface INestiaConfig {
      * Whether to use propagation mode or not.
      *
      * If being configured, interaction functions of the SDK library would perform
-     * the propagation mode. The propagation mode means that never throwing
-     * exception even when status code is not 200 (or 201), but just returning the
+     * propagation mode. HTTP failure statuses are returned through the
      * {@link IPropagation} typed instance, which can specify its body type through
-     * discriminated union determined by status code.
+     * discriminated union determined by status code. Transport, decoding and
+     * configured assertion failures can still throw.
      *
      * @default false
      */
@@ -81,9 +92,10 @@ export interface INestiaConfig {
     /**
      * Whether to clone DTO structures or not.
      *
-     * If being configured, all of DTOs used in the backend server would be cloned
-     * into the `structures` directory, and the SDK library would be refer to the
-     * cloned DTOs instead of the original.
+     * If enabled, named DTOs reachable from analyzed routes are emitted into
+     * `structures`, with anonymous forms written inline. HTTP and MCP DTOs use
+     * their wire metadata; supported WebSocket declarations are copied from local
+     * sources, while external or unsupported imports retain source links.
      *
      * @default false
      */
@@ -91,8 +103,10 @@ export interface INestiaConfig {
     /**
      * Whether to wrap DTO by primitive type.
      *
-     * If you don't configure this property as `false`, all of DTOs in the SDK
-     * library would be automatically wrapped by {@link Primitive} type.
+     * Unless false, source DTO aliases use Primitive for JSON bodies and
+     * responses, and Resolved for query, headers and other resolved wire forms.
+     * Clone mode writes the analyzed metadata directly; multipart bodies use
+     * FormDataInput and binary responses use ReadableStream.
      *
      * For refenrece, if a DTO type be capsuled by the {@link Primitive} type, all
      * of methods in the DTO type would be automatically erased. Also, if the DTO
@@ -105,9 +119,10 @@ export interface INestiaConfig {
     /**
      * Whether to assert parameter types or not.
      *
-     * If you configure this property to be `true`, all of the function parameters
-     * of SDK library would be checked through [`typia.assert<T>()`
-     * function](https://typia.io/docs/validators/assert/).
+     * If true, HTTP path, query and body arguments are checked through
+     * [`typia.assert<T>()` function](https://typia.io/docs/validators/assert/).
+     * The connection, connection headers, WebSocket and MCP arguments are outside
+     * this option.
      *
      * This option would make your SDK library compilation time a little bit
      * slower, but would enahcne the type safety even in the runtime level.
@@ -116,16 +131,13 @@ export interface INestiaConfig {
      */
     assert?: boolean;
     /**
-     * Whether to optimize JSON string conversion 10x faster or not.
-     *
-     * If you configure this property to be `true`, the SDK library would utilize
-     * the [`typia.assertStringify<T>()
-     * function`](https://github.com/samchon/typia#enhanced-json) to boost up JSON
-     * serialization speed and ensure type safety.
+     * Generates specialized JSON serialization for JSON and encrypted request
+     * bodies.
      *
-     * This option would make your SDK library compilation time a little bit
-     * slower, but would enhance JSON serialization speed 10x faster. Also, it can
-     * ensure type safety even in the runtime level.
+     * When enabled, the SDK emits a `typia.json.assertStringify` function for the
+     * body type. With `assert` enabled, argument validation runs separately and
+     * serialization uses `typia.json.stringify` without repeating the assertion.
+     * Compilation and runtime costs depend on the body type and workload.
      *
      * @default false
      */
@@ -135,6 +147,12 @@ export declare namespace INestiaConfig {
     /**
      * List of files or directories to include or exclude to specifying the NestJS
      * controllers.
+     *
+     * @evidence contracts/common.md#principled-implementation Include lists select controller files or directories and exclude lists remove files from that selection.
+     * @evidence contracts/common.md#clear-and-simple-design A two-member record.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+     * @evidence contracts/portability.md#os-neutral-implementation Include and exclude strings represent native files, directories or glob patterns. SourceFinder owns resolving them against the current working directory and distinguishing literal existing paths from wildcard suffixes.
      */
     interface IInput {
         /** List of files or directories containing the NestJS controller classes. */
@@ -142,7 +160,15 @@ export declare namespace INestiaConfig {
         /** List of files or directories to be excluded. */
         exclude?: string[];
     }
-    /** Building `swagger.json` is also possible. */
+    /**
+     * Building `swagger.json` is also possible.
+     *
+     * @evidence contracts/common.md#principled-implementation The output path is required and every other option refines the composed OpenAPI document before it is written.
+     * @evidence contracts/common.md#clear-and-simple-design A flat record of options with one callback.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the type describes and the meaning of its members.
+     * @evidence contracts/portability.md#os-neutral-implementation output is a native destination interpreted by path.parse/resolve in SwaggerGenerator; a nonempty extension denotes a file and otherwise the destination is a directory. Server URLs and operation paths retain protocol spelling independently of that filesystem boundary.
+     */
     interface ISwaggerConfig {
         /**
          * Response path of the `swagger.json`.
@@ -155,12 +181,11 @@ export declare namespace INestiaConfig {
         /**
          * OpenAPI version.
          *
-         * If you configure this property to be `2.0` or `3.0`, the newly generated
-         * `swagger.json` file would follow the specified OpenAPI version. The newly
-         * generated `swagger.json` file would be downgraded from the OpenAPI v3.1
-         * specification by {@link OpenApi.downgrade} method.
+         * If you configure this property to be `2.0`, `3.0`, or `3.1`, the newly
+         * generated `swagger.json` file would follow the specified OpenAPI version,
+         * downgraded from the OpenAPI v3.2 specification.
          *
-         * @default 3.1
+         * @default 3.2
          */
         openapi?: "2.0" | "3.0" | "3.1" | "3.2";
         /**
@@ -178,10 +203,12 @@ export declare namespace INestiaConfig {
          * Whether to include additional information or not.
          *
          * If configured to be `true`, those properties would be added into each API
-         * endpoinnt.
+         * endpoint.
          *
-         * - `x-nestia-method`
-         * - `x-nestia-namespace` ` `x-nestia-jsDocTags`
+         * - `x-nestia-method`: the HTTP method, such as `"GET"`
+         * - `x-nestia-namespace`: the SDK function's accessor, such as
+         *   `"bbs.articles.index"`
+         * - `x-nestia-jsDocTags`: the JSDoc tags of the controller method
          *
          * @default false
          */
@@ -199,7 +226,10 @@ export declare namespace INestiaConfig {
          *
          * When generating `swagger.json` file through `nestia`, if your controllers
          * or theirs methods have a security key which is not enrolled in here
-         * property, it would be an error.
+         * property, it would be an error. So would an OAuth2 scope none of the
+         * scheme's flows declares, and, for an OpenAPI `3.0` or `2.0` document,
+         * scopes on a scheme other than OAuth2 or OpenID Connect, which those
+         * versions require to be empty; from `3.1` on they list role names.
          */
         security?: Record<string, OpenApi.ISecurityScheme>;
         /**
@@ -219,7 +249,12 @@ export declare namespace INestiaConfig {
          * If you configure this property to be `true`, the query DTO would be
          * decomposed into individual query parameters per each property. Otherwise
          * you set it to be `false`, the query DTO would be one object type which
-         * contains all of query parameters.
+         * contains all of query parameters, spread into its keys by `style: form`
+         * and `explode: true`.
+         *
+         * Swagger 2.0 has no object query parameter, and no OpenAPI version can
+         * spread an object into headers, so a query DTO of a Swagger 2.0 document
+         * and a headers DTO are decomposed regardless of this property.
          *
          * @default true
          */
@@ -229,6 +264,11 @@ export declare namespace INestiaConfig {
          *
          * @param props Properties of the API endpoint.
          * @returns Operation ID.
+         * @evidence contracts/common.md#principled-implementation An explicit @operationId tag takes precedence; otherwise this callback receives the four identifying facts once for the composed operation and supplies its identifier.
+         * @evidence contracts/common.md#clear-and-simple-design One optional callback with a single argument object.
+         * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a caller-supplied function and nothing about a particular naming scheme is built in.
+         * @evidence contracts/common.md#meaningful-documentation The comment documents the arguments and the result.
+         * @evidenceExclude contracts/portability.md#os-neutral-implementation This callback receives HTTP endpoint identity and returns an OpenAPI identifier; it owns no native pathname or process boundary.
          */
         operationId?(props: {
             class: string;

package/lib/NestiaSdkApplication.d.ts

@@ -1,10 +1,70 @@
 import { INestiaConfig } from "./INestiaConfig";
+/**
+ * Runs the generators of `@nestia/sdk` over one configuration.
+ *
+ * Each method validates the configuration for the output it needs, analyzes the
+ * controllers and the TypeScript metadata, reports every error at once, and
+ * then generates.
+ *
+ * @evidence contracts/common.md#principled-implementation The shared pipeline reflects controllers, types routes from transform metadata, assigns accessors and rejects collected analysis errors before writing. SDK-specific representability checks are attached by sdk and SDK-producing all; e2e currently invokes the SDK writer without that additional validation callback.
+ * @evidence contracts/common.md#clear-and-simple-design One class with four public generators over one private pipeline; directory assertion, title, and error report are module-private helpers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No controller or route name is special-cased; the same pipeline serves the CLI and programmatic callers.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the four generators and that the errors of an analysis are reported together.
+ * @evidence contracts/portability.md#os-neutral-implementation Output checks and diagnostic locations use Node fs.stat and path operations; controller compilation and output writes remain owned by ConfigAnalyzer and the generators. Filesystem errors distinguish missing/non-directory locations from other native failures.
+ */
 export declare class NestiaSdkApplication {
     private readonly config;
     constructor(config: INestiaConfig);
+    /**
+     * Generates everything the configuration asks for: the SDK and its e2e tests
+     * when `output` is set, and the Swagger document when `swagger` is set.
+     *
+     * It throws when neither `output` nor `swagger.output` is configured.
+     *
+     * @evidence contracts/common.md#principled-implementation The SDK validation is attached only when an SDK is generated, so a Swagger-only run does not fail on SDK rules, and the e2e tests are generated after the SDK they import.
+     * @evidence contracts/common.md#clear-and-simple-design One method that composes the generators inside the shared pipeline.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The error names the properties a caller can configure; none is stale.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what is generated and the failure.
+     * @evidence contracts/portability.md#os-neutral-implementation all delegates configured output creation to the native writers and does not apply the explicit parent-directory checks used by sdk/e2e/swagger. Diagnostic source paths are rendered relative to the current native working directory.
+     */
     all(): Promise<void>;
+    /**
+     * Generates the SDK and the automatic e2e test functions.
+     *
+     * It throws when `output` or `e2e` is missing, or when the parent directory
+     * of either does not exist.
+     *
+     * @evidence contracts/common.md#principled-implementation The e2e functions import the generated SDK, so the SDK is generated first, and both parent directories are asserted before any analysis runs.
+     * @evidence contracts/common.md#clear-and-simple-design One method over the shared pipeline.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The directory check follows the configuration and no path is special-cased.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the requirements and the failures.
+     * @evidence contracts/portability.md#os-neutral-implementation path.resolve obtains each native parent and fs.stat follows symlinks to verify a directory before analysis. ENOENT/ENOTDIR become configuration diagnostics; permission and other filesystem errors propagate without a platform-specific shell fallback.
+     */
     e2e(): Promise<void>;
+    /**
+     * Generates the SDK library.
+     *
+     * It throws when `output` is missing or its parent directory does not exist.
+     *
+     * @evidence contracts/common.md#principled-implementation The SDK validation runs after route typing and before the generator, so a route the SDK cannot express is reported instead of written.
+     * @evidence contracts/common.md#clear-and-simple-design One method over the shared pipeline.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The directory check follows the configuration.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the requirement and the failures.
+     * @evidence contracts/portability.md#os-neutral-implementation The configured output parent is resolved through Node path and verified by fs.stat, including linked directories. Generator writes use their own native boundaries; this entry does not infer case identity from an OS name.
+     */
     sdk(): Promise<void>;
+    /**
+     * Generates the Swagger document.
+     *
+     * It throws when `swagger.output` is missing or the directory that will hold
+     * the document does not exist; the output may be a file or a directory.
+     *
+     * @evidence contracts/common.md#principled-implementation The directory to check is the parent of a file path with an extension and the path itself otherwise, which is how the generator decides where to write.
+     * @evidence contracts/common.md#clear-and-simple-design One method over the shared pipeline.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule is the generator's own output rule.
+     * @evidence contracts/common.md#meaningful-documentation The comment states the requirement and the two output forms.
+     * @evidence contracts/portability.md#os-neutral-implementation path.parse/resolve decide the native containing directory from whether the output has an extension, matching SwaggerGenerator's destination rule. The common directory check distinguishes missing paths from non-directory entries and propagates other filesystem errors.
+     */
     swagger(): Promise<void>;
     private generate;
 }