@visulima/jsdoc-open-api 3.0.0-alpha.4 → 3.0.0-alpha.6

package/dist/packem_shared/generateCommand-B1t3VSDX.mjs

@@ -0,0 +1,15 @@
+import { exit } from 'node:process';
+import generateCommand$1 from './generateCommand-CZEFuXr9.mjs';
+
+const generateCommand = (program, commandName = "generate", configName = ".openapirc.js") => {
+  program.command(commandName).description("Generates OpenAPI (Swagger) documentation from JSDoc's").usage("[options] <path ...>").argument("[path ...]", "Paths to files or directories to parse").option("-c, --config [.openapirc.js]", "@visulima/jsdoc-open-api config file path.").option("-o, --output [swaggerSpec.json]", "Output swagger specification.").option("-v, --verbose", "Verbose output.").option("-d, --very-verbose", "Very verbose output.").action(async (paths, options) => {
+    try {
+      await generateCommand$1(configName, paths, options);
+    } catch (error) {
+      console.error(error);
+      exit(1);
+    }
+  });
+};
+
+export { generateCommand as default };

package/dist/packem_shared/generateCommand-CZEFuXr9.mjs

@@ -0,0 +1,83 @@
+import { lstat, realpath, mkdir, writeFile } from 'node:fs/promises';
+import { normalize, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { collect } from '@visulima/fs';
+import { MultiBar, Presets } from 'cli-progress';
+import { v as validate, D as DEFAULT_EXCLUDE } from './validate-DZHaKH07.mjs';
+import commentsToOpenApi from './jsDocumentCommentsToOpenApi-eOlxMuMO.mjs';
+import parseFile from './parseFile-Bxis7tbW.mjs';
+import SpecBuilder from './SpecBuilder-B7YiF7zR.mjs';
+import commentsToOpenApi$1 from './swaggerJsDocumentCommentsToOpenApi-Cb5s1J29.mjs';
+
+const generateCommand = async (configName, paths, options) => {
+  let openapiConfig = {
+    exclude: [],
+    swaggerDefinition: {}
+  };
+  try {
+    let config = await import(pathToFileURL(normalize(options.config ?? configName)).href);
+    if (config?.default) {
+      config = config.default;
+    }
+    openapiConfig = config;
+  } catch {
+    throw new Error(`No config file found, on: ${options.config ?? ".openapirc.js"}
+`);
+  }
+  const multibar = new MultiBar(
+    {
+      clearOnComplete: false,
+      format: "{value}/{total} | {bar} | {filename}",
+      hideCursor: true
+    },
+    Presets.shades_grey
+  );
+  const spec = new SpecBuilder(openapiConfig.swaggerDefinition);
+  const skip = /* @__PURE__ */ new Set([...DEFAULT_EXCLUDE, ...openapiConfig.exclude]);
+  for await (const dir of paths) {
+    (await lstat(dir)).isDirectory();
+    const realDirectory = await realpath(dir);
+    const files = await collect(realDirectory, {
+      extensions: openapiConfig.extensions ?? [".js", ".cjs", ".mjs", ".ts", ".tsx", ".jsx", ".yaml", ".yml"],
+      followSymlinks: openapiConfig.followSymlinks ?? false,
+      match: openapiConfig.include,
+      skip: [...skip]
+    });
+    if (options.verbose ?? options.veryVerbose) {
+      console.log(`
+Found ${String(files.length)} files in ${realDirectory}`);
+    }
+    if (options.veryVerbose) {
+      console.log(files);
+    }
+    const bar = multibar.create(files.length, 0);
+    files.forEach((file) => {
+      if (options.verbose) {
+        console.log(`Parsing file ${file}`);
+      }
+      bar.increment(1, { filename: realDirectory });
+      const parsedJsDocumentFile = parseFile(file, commentsToOpenApi, options.verbose);
+      spec.addData(parsedJsDocumentFile.map((item) => item.spec));
+      const parsedSwaggerJsDocumentFile = parseFile(file, commentsToOpenApi$1, options.verbose);
+      spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+    });
+  }
+  if (options.verbose) {
+    console.log("Validating swagger spec");
+  }
+  if (options.veryVerbose) {
+    console.log(JSON.stringify(spec, null, 2));
+  }
+  await validate(JSON.parse(JSON.stringify(spec)));
+  const output = options.output ?? "swagger.json";
+  multibar.stop();
+  if (options.verbose) {
+    console.log(`Written swagger spec to "${output}" file`);
+  }
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, JSON.stringify(spec, null, 2));
+  console.log(`
+Swagger specification is ready, check the "${output}" file.`);
+};
+
+export { generateCommand as default };

package/dist/packem_shared/generateCommand-CmyavGTZ.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+const node_process = require('node:process');
+const generateCommand$1 = require('./generateCommand-Cu0UQUh8.cjs');
+
+const generateCommand = (program, commandName = "generate", configName = ".openapirc.js") => {
+  program.command(commandName).description("Generates OpenAPI (Swagger) documentation from JSDoc's").usage("[options] <path ...>").argument("[path ...]", "Paths to files or directories to parse").option("-c, --config [.openapirc.js]", "@visulima/jsdoc-open-api config file path.").option("-o, --output [swaggerSpec.json]", "Output swagger specification.").option("-v, --verbose", "Verbose output.").option("-d, --very-verbose", "Very verbose output.").action(async (paths, options) => {
+    try {
+      await generateCommand$1(configName, paths, options);
+    } catch (error) {
+      console.error(error);
+      node_process.exit(1);
+    }
+  });
+};
+
+module.exports = generateCommand;

package/dist/packem_shared/generateCommand-Cu0UQUh8.cjs

@@ -0,0 +1,85 @@
+'use strict';
+
+const promises = require('node:fs/promises');
+const path = require('node:path');
+const node_url = require('node:url');
+const fs = require('@visulima/fs');
+const cliProgress = require('cli-progress');
+const validate = require('./validate-FKieC3ln.cjs');
+const jsDocumentCommentsToOpenApi = require('./jsDocumentCommentsToOpenApi-C8kxIQH2.cjs');
+const parseFile = require('./parseFile-BJwu_na4.cjs');
+const SpecBuilder = require('./SpecBuilder-CCESkmm5.cjs');
+const swaggerJsDocumentCommentsToOpenApi = require('./swaggerJsDocumentCommentsToOpenApi-JFymRz50.cjs');
+
+const generateCommand = async (configName, paths, options) => {
+  let openapiConfig = {
+    exclude: [],
+    swaggerDefinition: {}
+  };
+  try {
+    let config = await import(node_url.pathToFileURL(path.normalize(options.config ?? configName)).href);
+    if (config?.default) {
+      config = config.default;
+    }
+    openapiConfig = config;
+  } catch {
+    throw new Error(`No config file found, on: ${options.config ?? ".openapirc.js"}
+`);
+  }
+  const multibar = new cliProgress.MultiBar(
+    {
+      clearOnComplete: false,
+      format: "{value}/{total} | {bar} | {filename}",
+      hideCursor: true
+    },
+    cliProgress.Presets.shades_grey
+  );
+  const spec = new SpecBuilder(openapiConfig.swaggerDefinition);
+  const skip = /* @__PURE__ */ new Set([...validate.DEFAULT_EXCLUDE, ...openapiConfig.exclude]);
+  for await (const dir of paths) {
+    (await promises.lstat(dir)).isDirectory();
+    const realDirectory = await promises.realpath(dir);
+    const files = await fs.collect(realDirectory, {
+      extensions: openapiConfig.extensions ?? [".js", ".cjs", ".mjs", ".ts", ".tsx", ".jsx", ".yaml", ".yml"],
+      followSymlinks: openapiConfig.followSymlinks ?? false,
+      match: openapiConfig.include,
+      skip: [...skip]
+    });
+    if (options.verbose ?? options.veryVerbose) {
+      console.log(`
+Found ${String(files.length)} files in ${realDirectory}`);
+    }
+    if (options.veryVerbose) {
+      console.log(files);
+    }
+    const bar = multibar.create(files.length, 0);
+    files.forEach((file) => {
+      if (options.verbose) {
+        console.log(`Parsing file ${file}`);
+      }
+      bar.increment(1, { filename: realDirectory });
+      const parsedJsDocumentFile = parseFile(file, jsDocumentCommentsToOpenApi, options.verbose);
+      spec.addData(parsedJsDocumentFile.map((item) => item.spec));
+      const parsedSwaggerJsDocumentFile = parseFile(file, swaggerJsDocumentCommentsToOpenApi, options.verbose);
+      spec.addData(parsedSwaggerJsDocumentFile.map((item) => item.spec));
+    });
+  }
+  if (options.verbose) {
+    console.log("Validating swagger spec");
+  }
+  if (options.veryVerbose) {
+    console.log(JSON.stringify(spec, null, 2));
+  }
+  await validate.validate(JSON.parse(JSON.stringify(spec)));
+  const output = options.output ?? "swagger.json";
+  multibar.stop();
+  if (options.verbose) {
+    console.log(`Written swagger spec to "${output}" file`);
+  }
+  await promises.mkdir(path.dirname(output), { recursive: true });
+  await promises.writeFile(output, JSON.stringify(spec, null, 2));
+  console.log(`
+Swagger specification is ready, check the "${output}" file.`);
+};
+
+module.exports = generateCommand;

package/dist/packem_shared/initCommand-B6Z9EXHP.mjs

@@ -0,0 +1,15 @@
+import { exit } from 'node:process';
+import initCommand$1 from './initCommand-zE4VRDGW.mjs';
+
+const initCommand = (program, commandName = "init", description = "Inits a pre-configured @visulima/jsdoc-open-api config file.", configName = ".openapirc.js") => {
+  program.command(commandName).description(description).action(() => {
+    try {
+      initCommand$1(configName);
+    } catch (error) {
+      console.error(error);
+      exit(1);
+    }
+  });
+};
+
+export { initCommand as default };

package/dist/packem_shared/initCommand-Ch-72dKZ.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+const node_fs = require('node:fs');
+const fs = require('@visulima/fs');
+
+const initCommand = (configName, packageJsonPath = process.cwd()) => {
+  if (node_fs.existsSync(configName)) {
+    throw new Error("Config file already exists");
+  }
+  const packagePath = fs.findUpSync("package.json", {
+    cwd: node_fs.realpathSync(packageJsonPath)
+  });
+  let exportTemplate = "module.exports =";
+  if (packagePath) {
+    const packageJson = fs.readJsonSync(packagePath);
+    console.info(`Found package.json at "${packagePath}"`);
+    if (packageJson.type === "module") {
+      console.info("Found package.json with type: module, using ES6 as export for the config file");
+      exportTemplate = "export default";
+    }
+  } else {
+    console.info("No package.json found");
+  }
+  node_fs.writeFileSync(
+    configName,
+    `${exportTemplate} {
+  exclude: [
+    'coverage/**',
+    '.github/**',
+    'packages/*/test{,s}/**',
+    '**/*.d.ts',
+    'test{,s}/**',
+    'test{,-*}.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}',
+    '**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}',
+    '**/__tests__/**',
+    '**/{ava,babel,nyc}.config.{js,cjs,mjs}',
+    '**/jest.config.{js,cjs,mjs,ts}',
+    '**/{karma,rollup,webpack}.config.js',
+    '**/.{eslint,mocha}rc.{js,cjs}',
+    '**/.{travis,yarnrc}.yml',
+    '**/{docker-compose,docker}.yml',
+    '**/.yamllint.{yaml,yml}',
+    '**/node_modules/**',
+    '**/pnpm-lock.yaml',
+    '**/pnpm-workspace.yaml',
+    '**/{package,package-lock}.json',
+    '**/yarn.lock',
+    '**/package.json5',
+    '**/.next/**',
+  ],
+  followSymlinks: false,
+  swaggerDefinition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'API',
+      version: '1.0.0',
+    },
+  },
+};
+`
+  );
+  console.log(`Created "${configName}"`);
+};
+
+module.exports = initCommand;

package/dist/packem_shared/initCommand-D3yVEMwO.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+const node_process = require('node:process');
+const initCommand$1 = require('./initCommand-Ch-72dKZ.cjs');
+
+const initCommand = (program, commandName = "init", description = "Inits a pre-configured @visulima/jsdoc-open-api config file.", configName = ".openapirc.js") => {
+  program.command(commandName).description(description).action(() => {
+    try {
+      initCommand$1(configName);
+    } catch (error) {
+      console.error(error);
+      node_process.exit(1);
+    }
+  });
+};
+
+module.exports = initCommand;

package/dist/packem_shared/initCommand-zE4VRDGW.mjs

@@ -0,0 +1,63 @@
+import { existsSync, realpathSync, writeFileSync } from 'node:fs';
+import { findUpSync, readJsonSync } from '@visulima/fs';
+
+const initCommand = (configName, packageJsonPath = process.cwd()) => {
+  if (existsSync(configName)) {
+    throw new Error("Config file already exists");
+  }
+  const packagePath = findUpSync("package.json", {
+    cwd: realpathSync(packageJsonPath)
+  });
+  let exportTemplate = "module.exports =";
+  if (packagePath) {
+    const packageJson = readJsonSync(packagePath);
+    console.info(`Found package.json at "${packagePath}"`);
+    if (packageJson.type === "module") {
+      console.info("Found package.json with type: module, using ES6 as export for the config file");
+      exportTemplate = "export default";
+    }
+  } else {
+    console.info("No package.json found");
+  }
+  writeFileSync(
+    configName,
+    `${exportTemplate} {
+  exclude: [
+    'coverage/**',
+    '.github/**',
+    'packages/*/test{,s}/**',
+    '**/*.d.ts',
+    'test{,s}/**',
+    'test{,-*}.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}',
+    '**/*{.,-}test.{js,cjs,mjs,ts,tsx,jsx,yaml,yml}',
+    '**/__tests__/**',
+    '**/{ava,babel,nyc}.config.{js,cjs,mjs}',
+    '**/jest.config.{js,cjs,mjs,ts}',
+    '**/{karma,rollup,webpack}.config.js',
+    '**/.{eslint,mocha}rc.{js,cjs}',
+    '**/.{travis,yarnrc}.yml',
+    '**/{docker-compose,docker}.yml',
+    '**/.yamllint.{yaml,yml}',
+    '**/node_modules/**',
+    '**/pnpm-lock.yaml',
+    '**/pnpm-workspace.yaml',
+    '**/{package,package-lock}.json',
+    '**/yarn.lock',
+    '**/package.json5',
+    '**/.next/**',
+  ],
+  followSymlinks: false,
+  swaggerDefinition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'API',
+      version: '1.0.0',
+    },
+  },
+};
+`
+  );
+  console.log(`Created "${configName}"`);
+};
+
+export { initCommand as default };

package/dist/packem_shared/jsDocumentCommentsToOpenApi-C8kxIQH2.cjs

@@ -0,0 +1,334 @@
+'use strict';
+
+const commentParser = require('comment-parser');
+const mergeWith = require('lodash.mergewith');
+const customizer = require('./customizer-DDFwFqJl.cjs');
+
+const _interopDefaultCompat = e => e && typeof e === 'object' && 'default' in e ? e.default : e;
+
+const mergeWith__default = /*#__PURE__*/_interopDefaultCompat(mergeWith);
+
+const fixSecurityObject = (thing) => {
+  if (thing.security) {
+    thing.security = Object.keys(thing.security).map((s) => {
+      return {
+        [s]: thing.security[s]
+      };
+    });
+  }
+};
+const primitiveTypes = /* @__PURE__ */ new Set(["array", "boolean", "integer", "number", "object", "string"]);
+const formatMap = {
+  binary: "string",
+  byte: "string",
+  date: "string",
+  "date-time": "string",
+  double: "number",
+  float: "number",
+  int32: "integer",
+  int64: "integer",
+  password: "string"
+};
+const parseDescription = (tag) => {
+  const rawType = tag.type;
+  const isArray = rawType.endsWith("[]");
+  const parsedType = rawType.replace(/\[]$/, "");
+  const isPrimitive = primitiveTypes.has(parsedType);
+  const isFormat = Object.keys(formatMap).includes(parsedType);
+  let defaultValue;
+  if (tag.default) {
+    switch (parsedType) {
+      case "double":
+      case "float":
+      case "number": {
+        defaultValue = Number.parseFloat(tag.default);
+        break;
+      }
+      case "int32":
+      case "int64":
+      case "integer": {
+        defaultValue = Number.parseInt(tag.default, 10);
+        break;
+      }
+      default: {
+        defaultValue = tag.default;
+        break;
+      }
+    }
+  }
+  let rootType;
+  if (isPrimitive) {
+    rootType = { default: defaultValue, type: parsedType };
+  } else if (isFormat) {
+    rootType = {
+      default: defaultValue,
+      format: parsedType,
+      type: formatMap[parsedType]
+    };
+  } else {
+    rootType = { $ref: `#/components/schemas/${parsedType}` };
+  }
+  let schema = isArray ? {
+    items: {
+      ...rootType
+    },
+    type: "array"
+  } : {
+    ...rootType
+  };
+  if (parsedType === "") {
+    schema = void 0;
+  }
+  let description = tag.description.trim().replace(/^- /u, "");
+  if (description === "") {
+    description = void 0;
+  }
+  return {
+    description,
+    name: tag.name,
+    rawType,
+    required: !tag.optional,
+    schema
+  };
+};
+const tagsToObjects = (tags, verbose) => tags.map((tag) => {
+  const parsedResponse = parseDescription(tag);
+  let nameAndDescription = "";
+  if (parsedResponse.name) {
+    nameAndDescription += parsedResponse.name;
+  }
+  if (parsedResponse.description) {
+    nameAndDescription += ` ${parsedResponse.description.trim()}`;
+  }
+  switch (tag.tag) {
+    case "bodyComponent": {
+      return {
+        requestBody: {
+          $ref: `#/components/requestBodies/${parsedResponse.rawType}`
+        }
+      };
+    }
+    case "bodyContent": {
+      return {
+        requestBody: {
+          content: {
+            [parsedResponse.name.replace(String.raw`*\/*`, "*/*")]: {
+              schema: parsedResponse.schema
+            }
+          }
+        }
+      };
+    }
+    case "bodyDescription": {
+      return { requestBody: { description: nameAndDescription } };
+    }
+    case "bodyExample": {
+      const [contentType, example] = parsedResponse.name.split(".");
+      return {
+        requestBody: {
+          content: {
+            [contentType]: {
+              examples: {
+                [example]: {
+                  $ref: `#/components/examples/${parsedResponse.rawType}`
+                }
+              }
+            }
+          }
+        }
+      };
+    }
+    case "bodyRequired": {
+      return { requestBody: { required: true } };
+    }
+    case "callback": {
+      return {
+        callbacks: {
+          [parsedResponse.name]: {
+            $ref: `#/components/callbacks/${parsedResponse.rawType}`
+          }
+        }
+      };
+    }
+    case "cookieParam":
+    case "headerParam":
+    case "pathParam":
+    case "queryParam": {
+      return {
+        parameters: [
+          {
+            description: parsedResponse.description,
+            in: tag.tag.replace(/Param$/u, ""),
+            name: parsedResponse.name,
+            required: parsedResponse.required,
+            schema: parsedResponse.schema
+          }
+        ]
+      };
+    }
+    case "deprecated": {
+      return { deprecated: true };
+    }
+    case "description":
+    case "operationId":
+    case "summary": {
+      return { [tag.tag]: nameAndDescription };
+    }
+    case "externalDocs": {
+      return {
+        externalDocs: {
+          description: parsedResponse.description,
+          url: parsedResponse.name
+        }
+      };
+    }
+    case "paramComponent": {
+      return {
+        parameters: [{ $ref: `#/components/parameters/${parsedResponse.rawType}` }]
+      };
+    }
+    case "response": {
+      return {
+        responses: {
+          [parsedResponse.name]: {
+            description: parsedResponse.description
+          }
+        }
+      };
+    }
+    case "responseComponent": {
+      return {
+        responses: {
+          [parsedResponse.name]: {
+            $ref: `#/components/responses/${parsedResponse.rawType}`
+          }
+        }
+      };
+    }
+    case "responseContent": {
+      const [status, contentType] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            content: {
+              [contentType]: {
+                schema: parsedResponse.schema
+              }
+            }
+          }
+        }
+      };
+    }
+    case "responseExample": {
+      const [status, contentType, example] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            content: {
+              [contentType]: {
+                examples: {
+                  [example]: {
+                    $ref: `#/components/examples/${parsedResponse.rawType}`
+                  }
+                }
+              }
+            }
+          }
+        }
+      };
+    }
+    case "responseHeader": {
+      const [status, header] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            headers: {
+              [header]: {
+                description: parsedResponse.description,
+                schema: parsedResponse.schema
+              }
+            }
+          }
+        }
+      };
+    }
+    case "responseHeaderComponent": {
+      const [status, header] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            headers: {
+              [header]: {
+                $ref: `#/components/headers/${parsedResponse.rawType}`
+              }
+            }
+          }
+        }
+      };
+    }
+    case "responseLink": {
+      const [status, link] = parsedResponse.name.split(".");
+      return {
+        responses: {
+          [status]: {
+            links: {
+              [link]: {
+                $ref: `#/components/links/${parsedResponse.rawType}`
+              }
+            }
+          }
+        }
+      };
+    }
+    case "security": {
+      const [security, scopeItem] = parsedResponse.name.split(".");
+      let scope = [];
+      if (scopeItem) {
+        scope = [scopeItem];
+      }
+      return {
+        security: { [security]: scope }
+      };
+    }
+    case "server": {
+      return {
+        servers: [
+          {
+            description: parsedResponse.description,
+            url: parsedResponse.name
+          }
+        ]
+      };
+    }
+    case "tag": {
+      return { tags: [nameAndDescription] };
+    }
+    default: {
+      return {};
+    }
+  }
+});
+const commentsToOpenApi = (fileContents, verbose) => {
+  const openAPIRegex = /^(GET|PUT|POST|DELETE|OPTIONS|HEAD|PATCH|TRACE) \/.*$/;
+  const jsDocumentComments = commentParser.parse(fileContents, { spacing: "preserve" });
+  return jsDocumentComments.filter((comment) => openAPIRegex.test(comment.description.trim())).map((comment) => {
+    const loc = comment.tags.length + 1;
+    const result = mergeWith__default({}, ...tagsToObjects(comment.tags), customizer.customizer);
+    fixSecurityObject(result);
+    const [method, path] = comment.description.split(" ");
+    const pathsObject = {
+      [path.trim()]: {
+        [method.toLowerCase().trim()]: {
+          ...result
+        }
+      }
+    };
+    const spec = JSON.parse(JSON.stringify({ paths: pathsObject }));
+    return {
+      loc,
+      spec
+    };
+  });
+};
+
+module.exports = commentsToOpenApi;