@nestia/sdk 13.0.4 → 14.0.1

package/src/factories/LiteralFactory.ts

@@ -1,4 +1,4 @@
-import { type Expression, factory } from "@ttsc/factory";
+import { type Expression, SyntaxKind, factory } from "@ttsc/factory";
 
 import { ExpressionFactory } from "./ExpressionFactory";
 import { IdentifierFactory } from "./IdentifierFactory";
@@ -30,7 +30,12 @@ export namespace LiteralFactory {
     if (typeof input === "number") return ExpressionFactory.number(input);
     if (typeof input === "string") return factory.createStringLiteral(input);
     if (typeof input === "bigint")
-      return factory.createStringLiteral(input.toString());
+      return input < BigInt(0)
+        ? factory.createPrefixUnaryExpression(
+            SyntaxKind.MinusToken,
+            factory.createBigIntLiteral((-input).toString()),
+          )
+        : factory.createBigIntLiteral(input.toString());
     if (typeof input === "function")
       return factory.createIdentifier("undefined");
     throw new TypeError("LiteralFactory.write: unsupported input type.");

package/src/generates/SdkGenerator.ts

@@ -118,7 +118,7 @@ export namespace SdkGenerator {
         props.errors.push({
           file: props.route.controller.file,
           class: props.route.controller.class.name,
-          function: props.route.name,
+          function: props.route.key,
           from: `parameter ${JSON.stringify(p.name)}`,
           contents: [`implicit (unnamed) parameter type.`],
         });
@@ -129,7 +129,7 @@ export namespace SdkGenerator {
           props.errors.push({
             file: props.route.controller.file,
             class: props.route.controller.class.name,
-            function: props.route.name,
+            function: props.route.key,
             from: `exception ${JSON.stringify(key)}`,
             contents: [`implicit (unnamed) exception type.`],
           });
@@ -140,7 +140,7 @@ export namespace SdkGenerator {
       props.errors.push({
         file: props.route.controller.file,
         class: props.route.controller.class.name,
-        function: props.route.name,
+        function: props.route.key,
         from: "success",
         contents: [`implicit (unnamed) return type.`],
       });

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,
@@ -211,7 +212,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 +240,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 +269,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);
+    });
+  };
+
+  /**
+   * 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;
   };
 
-  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;
+  /**
+   * 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/FilePrinter.ts

@@ -31,6 +31,34 @@ 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
+   */
+  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");
+  };
+
   export const enter = () =>
     factory.createExpressionStatement(factory.createIdentifier("\n"));
 

package/src/generates/internal/ImportDictionary.ts

@@ -59,6 +59,17 @@ export class ImportDictionary {
     }
   }
 
+  /** Every identifier the imports bind in the file. */
+  public locals(): string[] {
+    const output: string[] = [];
+    for (const { second: c } of this.components_) {
+      if (c.asterisk !== null) output.push(c.asterisk);
+      if (c.default !== null) output.push(c.default);
+      for (const { first: local } of c.elements) output.push(local);
+    }
+    return output;
+  }
+
   public external(props: ImportDictionary.IProps): string {
     const file: string = `node_modules/${props.file}`;
     return this.internal({

package/src/generates/internal/SdkAliasCollection.ts

@@ -16,6 +16,7 @@ import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkHttpParameterProgrammer } from "./SdkHttpParameterProgrammer";
 import { SdkTypeProgrammer } from "./SdkTypeProgrammer";
+import type { SdkWebSocketParameterProgrammer } from "./SdkWebSocketParameterProgrammer";
 
 export namespace SdkAliasCollection {
   export const name = ({ type }: { type: IReflectType }): TypeNode =>
@@ -82,7 +83,10 @@ export namespace SdkAliasCollection {
           .flat(),
       );
 
-  export const websocketProps = (route: ITypedWebSocketRoute): TypeNode =>
+  export const websocketProps = (
+    route: ITypedWebSocketRoute,
+    names: SdkWebSocketParameterProgrammer.INames,
+  ): TypeNode =>
     factory.createTypeLiteralNode([
       ...route.pathParameters.map((p) =>
         factory.createPropertySignature(
@@ -96,7 +100,7 @@ export namespace SdkAliasCollection {
         ? [
             factory.createPropertySignature(
               undefined,
-              "query",
+              names.query,
               undefined,
               factory.createTypeReferenceNode("Query"),
             ),
@@ -104,7 +108,7 @@ export namespace SdkAliasCollection {
         : []),
       factory.createPropertySignature(
         undefined,
-        "provider",
+        names.provider,
         undefined,
         factory.createTypeReferenceNode("Provider"),
       ),
@@ -233,7 +237,10 @@ export namespace SdkAliasCollection {
             branches.map((b) =>
               factory.createPropertySignature(
                 undefined,
-                factory.createNumericLiteral(b.status),
+                // a status range like "4XX" is no numeric literal
+                /^\d+$/.test(b.status)
+                  ? factory.createNumericLiteral(b.status)
+                  : factory.createStringLiteral(b.status),
                 undefined,
                 b.type,
               ),

package/src/generates/internal/SdkDistributionComposer.ts

@@ -29,17 +29,34 @@ export namespace SdkDistributionComposer {
         await replace({ root, output })(file);
 
       // INSTALL PACKAGES
+      //
+      // The package compiles with ttsc, which applies the typia transform the
+      // SDK's `assert` and `simulate` code needs through typia's own plugin;
+      // typia removed its `setup` command in 14.0.0.
       const v: IDependencies = await dependencies({
+        root,
         websocket: props.websocket,
       });
-      execute("npm install --save-dev rimraf");
-      execute(`npm install --save @nestia/fetcher@${v.version}`);
-      execute(`npm install --save typia@${v.typia}`);
-      if (props.mcp && v.mcp !== undefined)
-        execute(`npm install --save @modelcontextprotocol/sdk@${v.mcp}`);
-      if (props.websocket && v.tgrid !== undefined)
-        execute(`npm install --save tgrid@${v.tgrid}`);
-      execute("npx typia setup --manager npm");
+      // one install per dependency kind: each npm run resolves and reifies the
+      // whole tree again, and the runtime set lands together or not at all, so
+      // an interrupted setup never leaves @nestia/fetcher, which marks the
+      // package configured, without its peers
+      execute(
+        `npm install --save-dev rimraf ttsc@${v.ttsc} typescript@${v.typescript}`,
+      );
+      execute(
+        [
+          "npm install --save",
+          `@nestia/fetcher@${v.version}`,
+          `typia@${v.typia}`,
+          ...(props.mcp && v.mcp !== undefined
+            ? [`@modelcontextprotocol/sdk@${v.mcp}`]
+            : []),
+          ...(props.websocket && v.tgrid !== undefined
+            ? [`tgrid@${v.tgrid}`]
+            : []),
+        ].join(" "),
+      );
     } finally {
       process.chdir(root);
     }
@@ -82,7 +99,60 @@ export namespace SdkDistributionComposer {
       );
     };
 
+  /**
+   * The version of a package the project installed, exactly: the staged package
+   * must run the typia, and compile with the ttsc and TypeScript, the project
+   * itself uses, with the tgrid and MCP SDK its WebSocket and MCP functions
+   * import. `@nestia/sdk`'s own specifier is only the fallback, and a
+   * workspace's `catalog:` one names no version npm could install.
+   */
+  const installed = (
+    root: string,
+    name: string,
+    fallback: string | undefined,
+  ): string | undefined =>
+    manifestVersion(root, name) ??
+    (fallback !== undefined && fallback.startsWith("catalog:") === false
+      ? fallback
+      : undefined);
+
+  /**
+   * The version in the manifest of the package as installed. Not every package
+   * exports its `package.json`, as tgrid does not, and a subpath export may map
+   * it to a nested manifest of no name, as `@modelcontextprotocol/sdk` maps it
+   * to `dist/cjs/package.json`; so the manifest is the nearest `package.json`
+   * naming the package, at or above what the request resolves to.
+   */
+  const manifestVersion = (root: string, name: string): string | undefined => {
+    for (const request of [`${name}/package.json`, name]) {
+      let file: string;
+      try {
+        file = require.resolve(request, { paths: [root, __dirname] });
+      } catch {
+        continue;
+      }
+      for (let directory: string = path.dirname(file); ; ) {
+        try {
+          const json: { name?: unknown; version?: unknown } = JSON.parse(
+            fs.readFileSync(path.join(directory, "package.json"), "utf8"),
+          );
+          if (
+            json.name === name &&
+            typeof json.version === "string" &&
+            json.version.length !== 0
+          )
+            return json.version;
+        } catch {}
+        const parent: string = path.dirname(directory);
+        if (parent === directory) break;
+        directory = parent;
+      }
+    }
+    return undefined;
+  };
+
   const dependencies = async (opts: {
+    root: string;
     websocket: boolean;
   }): Promise<IDependencies> => {
     const content: string = await fs.promises.readFile(
@@ -98,20 +168,22 @@ export namespace SdkDistributionComposer {
       ...json.devDependencies,
       ...json.dependencies,
     };
-    const required = (key: "version" | "typia"): string => {
-      const value: string | undefined =
-        key === "version" ? json.version : dependencies[key];
+    const required = (key: string, value: string | undefined): string => {
       if (typeof value !== "string" || value.length === 0)
         throw new Error(
           `Unable to resolve ${key} version for SDK distribution.`,
         );
       return value;
     };
+    const version = (name: string): string | undefined =>
+      installed(opts.root, name, dependencies[name]);
     return {
-      version: required("version"),
-      typia: required("typia"),
-      tgrid: opts.websocket ? dependencies.tgrid : undefined,
-      mcp: dependencies["@modelcontextprotocol/sdk"],
+      version: required("@nestia/fetcher", json.version),
+      typia: required("typia", version("typia")),
+      ttsc: required("ttsc", version("ttsc")),
+      typescript: required("typescript", version("typescript")),
+      tgrid: opts.websocket ? version("tgrid") : undefined,
+      mcp: version("@modelcontextprotocol/sdk"),
     };
   };
 }
@@ -119,6 +191,8 @@ export namespace SdkDistributionComposer {
 interface IDependencies {
   version: string;
   typia: string;
+  ttsc: string;
+  typescript: string;
   tgrid: string | undefined;
   mcp: string | undefined;
 }