@nestia/sdk 14.0.0 → 14.0.2

package/src/generates/SwaggerGenerator.ts

@@ -13,6 +13,7 @@ import { Singleton } from "tstl";
 import type { IJsonSchemaCollection } from "typia";
 
 import { INestiaConfig } from "../INestiaConfig";
+import { PathAnalyzer } from "../analyses/PathAnalyzer";
 import {
   JsonSchemasProgrammer,
   MetadataSchema,
@@ -23,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");
@@ -39,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,
@@ -75,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[];
@@ -101,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 = (
@@ -127,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> => {
@@ -211,7 +254,8 @@ export namespace SwaggerGenerator {
         schemas: {},
         securitySchemes: config.security,
       },
-      tags: config.tags ?? [],
+      // a copy, because composing pushes each route's tags into this list
+      tags: clone(config.tags ?? []),
       "x-typia-emended-v12": true,
     };
   };
@@ -238,7 +282,12 @@ export namespace SwaggerGenerator {
     routes: ITypedHttpRoute[];
   }): void => {
     // SWAGGER CUSTOMIZER
-    const customizers: Array<() => void> = [];
+    const customizers: Array<{
+      route: ITypedHttpRoute;
+      method: OpenApi.Method;
+      path: string;
+      closures: Function[];
+    }> = [];
     const neighbor = {
       at: new Singleton(() => {
         const functor: Map<Function, Endpoint> = new Map();
@@ -262,63 +311,197 @@ export namespace SwaggerGenerator {
           (key: Accessor): OpenApi.IOperation | undefined => {
             const method: OpenApi.Method =
               key.method.toLowerCase() as OpenApi.Method;
-            const path: string =
+            const normalized: string =
               "/" +
               key.path
                 .split("/")
                 .filter((str) => !!str.length)
-                .map((str) =>
-                  str.startsWith(":") ? `{${str.substring(1)}}` : str,
-                )
                 .join("/");
+            // a route path, `:id`, as the router reads it; an accessor already
+            // in OpenAPI form, `{id}`, is taken as is
+            const path: string = normalized.includes(":")
+              ? PathAnalyzer.toOpenApi(normalized)
+              : normalized;
             return props.document.paths?.[path]?.[method];
           },
       ),
     };
 
     // COMPOSE OPERATIONS
+    const violations: string[] = [];
     for (const r of props.routes) {
-      const operation: OpenApi.IOperation = SwaggerOperationComposer.compose({
-        ...props,
-        route: r,
-      });
+      const method: OpenApi.Method = r.method.toLowerCase() as OpenApi.Method;
       const path: string = getPath(r);
       props.document.paths ??= {};
       props.document.paths[path] ??= {};
-      props.document.paths[path][r.method.toLowerCase() as "get"] = operation;
+      props.document.paths[path][method] = SwaggerOperationComposer.compose({
+        ...props,
+        route: r,
+      });
+      violations.push(
+        ...validateSecurity({
+          config: props.config,
+          route: r,
+          security: props.document.paths[path][method]!.security,
+        }),
+      );
 
       const closure: Function | Function[] | undefined = Reflect.getMetadata(
         "nestia/SwaggerCustomizer",
         r.controller.class.prototype,
-        r.name,
+        r.key,
       );
-      if (closure !== undefined) {
-        const array: Function[] = Array.isArray(closure) ? closure : [closure];
-        customizers.push(() => {
-          for (const closure of array)
-            closure({
-              swagger: props.document,
-              method: r.method,
-              path,
-              route: operation,
-              at: (func: Function) => neighbor.at.get().get(func),
-              get: (accessor: Accessor) => neighbor.get.get()(accessor),
-            } satisfies SwaggerCustomizer.IProps);
+      if (closure !== undefined)
+        customizers.push({
+          route: r,
+          method,
+          path,
+          closures: Array.isArray(closure) ? closure : [closure],
         });
-      }
     }
 
-    // DO CUSTOMIZE
-    for (const fn of customizers) fn();
+    if (violations.length !== 0)
+      throw new Error(
+        [
+          `Error on Swagger composition: invalid security requirements. Declare every scheme a route names, with its scopes, in the "security" of the Swagger configuration: "swagger.security" of "nestia.config.ts", or the configuration given to NestiaSwaggerComposer.document().`,
+          "",
+          "List of violations:",
+          ...violations,
+        ].join("\n"),
+      );
+
+    // DETACH, then DO CUSTOMIZE
+    detach(props.document);
+    // Each customizer receives the operation composed for its own route, found
+    // before any customizer runs, since one may move or delete paths.
+    const operations: OpenApi.IOperation[] = customizers.map(
+      (c) => props.document.paths![c.path]![c.method]!,
+    );
+    customizers.forEach((c, i) => {
+      for (const closure of c.closures)
+        closure({
+          swagger: props.document,
+          method: c.route.method,
+          path: c.path,
+          route: operations[i]!,
+          at: (func: Function) => neighbor.at.get().get(func),
+          get: (accessor: Accessor) => neighbor.get.get()(accessor),
+        } satisfies SwaggerCustomizer.IProps);
+    });
   };
 
-  const getPath = (route: ITypedHttpRoute): string => {
-    let str: string = route.path;
-    for (const param of route.pathParameters)
-      str = str.replace(`:${param.field}`, `{${param.field}}`);
-    return str;
+  /**
+   * Replaces every member of the composed document with a copy, in place.
+   *
+   * Operations still hold values nestia does not own by reference: decorator
+   * examples, `@ApiExtension` values, security requirements, and the configured
+   * servers, security schemes, and document info. They outlive the document,
+   * since route metadata and the configuration serve every composition in the
+   * process, so a `SwaggerCustomizer` or a caller editing one document edited
+   * all of them, and the next composition started from the edit. It runs before
+   * the customizers, which may then edit freely.
+   */
+  const detach = (document: OpenApi.IDocument): void => {
+    const copy: OpenApi.IDocument = clone(document);
+    for (const key of Object.keys(document))
+      delete (document as unknown as Record<string, unknown>)[key];
+    Object.assign(document, copy);
   };
 
+  /**
+   * Copies the arrays and plain objects `value` is built of, keeping every
+   * other value as it is.
+   *
+   * A document is edited as the tree its JSON is, so every reference to an
+   * array or plain object gets its own copy, except a reference back to an
+   * enclosing one, which stays circular. Values are not converted: a JSON copy
+   * would throw on a bigint example or turn a `Date` into a string before the
+   * customizer or caller that handles it runs.
+   */
+  const clone = <T>(
+    value: T,
+    ancestors: Map<object, object> = new Map(),
+  ): T => {
+    if (typeof value !== "object" || value === null) return value;
+    const prototype: unknown = Object.getPrototypeOf(value);
+    const array: boolean = Array.isArray(value);
+    if (!array && prototype !== Object.prototype && prototype !== null)
+      return value;
+    const circular: object | undefined = ancestors.get(value);
+    if (circular !== undefined) return circular as T;
+    const output: Record<string, unknown> = (
+      array ? new Array((value as unknown[]).length) : {}
+    ) as Record<string, unknown>;
+    ancestors.set(value, output);
+    for (const key of Object.keys(value))
+      Object.defineProperty(output, key, {
+        value: clone((value as Record<string, unknown>)[key], ancestors),
+        writable: true,
+        enumerable: true,
+        configurable: true,
+      });
+    ancestors.delete(value);
+    return output as T;
+  };
+
+  /**
+   * The violations of an operation's security requirements against the
+   * configured `swagger.security` schemes: a scheme it never declares, an
+   * OAuth2 scope no flow of the scheme declares, and, for an OpenAPI 3.0 or
+   * Swagger 2.0 document, scopes on a scheme other than OAuth2 or OpenID
+   * Connect, which those versions require to be empty. From 3.1 on, such a
+   * scheme's array lists the role names the operation requires. An OpenID
+   * Connect scheme lists no scopes of its own, so its scopes are not checked.
+   */
+  const validateSecurity = (props: {
+    config: Omit<INestiaConfig.ISwaggerConfig, "output">;
+    route: ITypedHttpRoute;
+    security: Record<string, string[]>[] | undefined;
+  }): string[] => {
+    const violations: string[] = [];
+    const report = (message: string): void => {
+      violations.push(
+        `  - ${message} (${props.route.controller.class.name}.${props.route.key}() at "${props.route.method} ${props.route.path}")`,
+      );
+    };
+    for (const requirement of props.security ?? [])
+      for (const [name, scopes] of Object.entries(requirement)) {
+        const scheme: OpenApi.ISecurityScheme | undefined =
+          props.config.security?.[name];
+        if (scheme === undefined)
+          report(`target security scheme "${name}" does not exist.`);
+        else if (scopes.length === 0 || scheme.type === "openIdConnect")
+          continue;
+        else if (scheme.type !== "oauth2") {
+          const version: string = props.config.openapi ?? "3.2";
+          if (version === "3.0" || version === "2.0")
+            report(
+              `target security scheme "${name}" is neither "oauth2" nor "openIdConnect" type, but you've configured the scopes, which OpenAPI ${version} requires to be empty.`,
+            );
+        } else {
+          const declared: Set<string> = new Set(
+            Object.values(scheme.flows ?? {}).flatMap((flow) =>
+              Object.keys(
+                (flow as { scopes?: Record<string, string> } | undefined)
+                  ?.scopes ?? {},
+              ),
+            ),
+          );
+          for (const scope of scopes)
+            if (declared.has(scope) === false)
+              report(
+                `target security scheme "${name}" does not have a specific scope "${scope}".`,
+              );
+        }
+      }
+    return violations;
+  };
+
+  // each parameter where the router reads it; a replacement by text would
+  // turn `:identity` into `{id}entity` for a path also holding `:id`
+  const getPath = (route: ITypedHttpRoute): string =>
+    PathAnalyzer.toOpenApi(route.path);
+
   const isSwaggerExcluded = (route: ITypedHttpRoute): boolean => {
     const controller: unknown = Reflect.getMetadata(
       "swagger/apiExcludeController",

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(
@@ -31,9 +50,61 @@ export namespace FilePrinter {
     );
   };
 
+  /**
+   * Writes a JSDoc tag so TypeScript reads its text back as it is.
+   *
+   * TypeScript takes a continued line's margin off up to the column the text
+   * began at: past `@<head> ` when the text starts on the tag's line, or the
+   * tag's own column when it starts on the next one. So a text whose first line
+   * is indented, such as an `@example`'s code, starts on the next line, and any
+   * other text continues at its first line's column. Either way every line
+   * keeps the indentation it has beyond the margin.
+   *
+   * @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());
+    while (lines.length !== 0 && lines[0] === "") lines.shift();
+    while (lines.length !== 0 && lines.at(-1) === "") lines.pop();
+    if (lines.length === 0) return `@${head}`;
+    else if (/^\s/.test(lines[0]!)) return [`@${head}`, ...lines].join("\n");
+    const margin: string = " ".repeat(head.length + 2);
+    return [
+      `@${head} ${lines[0]}`,
+      ...lines
+        .slice(1)
+        .map((line) => (line.length ? `${margin}${line}` : line)),
+    ].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[];