@f3liz/rescript-autogen-openapi 0.3.1

package/lib/es6/src/Types.mjs

@@ -0,0 +1,20 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as CodegenError from "./types/CodegenError.mjs";
+
+let Warning_toString = CodegenError.Warning.toString;
+
+let Warning_print = CodegenError.Warning.print;
+
+let Warning = {
+  toString: Warning_toString,
+  print: Warning_print
+};
+
+let CodegenError$1;
+
+export {
+  CodegenError$1 as CodegenError,
+  Warning,
+}
+/* No side effect */

package/lib/es6/src/bindings/Toposort.mjs

@@ -0,0 +1,12 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import Toposort from "toposort";
+
+function sortArray(nodes, edges) {
+  return Toposort.array(nodes, edges);
+}
+
+export {
+  sortArray,
+}
+/* toposort Not a pure module */

package/lib/es6/src/core/CodegenUtils.mjs

@@ -0,0 +1,261 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as JsConvertCase from "js-convert-case";
+
+function sanitizeIdentifier(str) {
+  return str.replaceAll("{", "").replaceAll("}", "").replaceAll("[", "").replaceAll("]", "").replaceAll(".", "_").replaceAll("-", "_").replaceAll("/", "_").replaceAll(" ", "_");
+}
+
+function generateTypeName(prefixOpt, path, suffix) {
+  let prefix = prefixOpt !== undefined ? prefixOpt : "";
+  let cleaned = sanitizeIdentifier(path.replaceAll("/", "_")).split("_").filter(part => part !== "").map(prim => JsConvertCase.toPascalCase(prim)).join("");
+  return prefix + cleaned + suffix;
+}
+
+function generateOperationName(operationId, path, method) {
+  if (operationId !== undefined) {
+    return JsConvertCase.toCamelCase(sanitizeIdentifier(operationId));
+  } else {
+    return method.toLowerCase() + path.split("/").filter(part => {
+      if (part !== "") {
+        return !part.startsWith("{");
+      } else {
+        return false;
+      }
+    }).map(prim => JsConvertCase.toCamelCase(prim)).join("");
+  }
+}
+
+function escapeString(str) {
+  return str.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\n").replaceAll("\r", "\\r").replaceAll("\t", "\\t");
+}
+
+function generateFileHeader(description) {
+  return `// ` + description + `
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT - This file is auto-generated
+
+`;
+}
+
+function indent(code, level) {
+  let spaces = "  ".repeat(level);
+  return code.split("\n").map(line => {
+    if (line.trim() === "") {
+      return "";
+    } else {
+      return spaces + line;
+    }
+  }).join("\n");
+}
+
+function trimMargin(text, marginPrefixOpt) {
+  let marginPrefix = marginPrefixOpt !== undefined ? marginPrefixOpt : "|";
+  return text.split("\n").map(line => {
+    let trimmed = line.trimStart();
+    if (trimmed.startsWith(marginPrefix)) {
+      return trimmed.slice(marginPrefix.length);
+    } else {
+      return line;
+    }
+  }).join("\n").trim();
+}
+
+let rescriptKeywords = [
+  "and",
+  "as",
+  "assert",
+  "async",
+  "await",
+  "catch",
+  "class",
+  "constraint",
+  "do",
+  "done",
+  "downto",
+  "else",
+  "end",
+  "exception",
+  "external",
+  "false",
+  "for",
+  "fun",
+  "function",
+  "functor",
+  "if",
+  "in",
+  "include",
+  "inherit",
+  "initializer",
+  "lazy",
+  "let",
+  "method",
+  "module",
+  "mutable",
+  "new",
+  "nonrec",
+  "object",
+  "of",
+  "open",
+  "or",
+  "private",
+  "rec",
+  "sig",
+  "struct",
+  "switch",
+  "then",
+  "to",
+  "true",
+  "try",
+  "type",
+  "val",
+  "virtual",
+  "when",
+  "while",
+  "with"
+];
+
+function escapeKeyword(name) {
+  if (rescriptKeywords.includes(name)) {
+    return name + "_";
+  } else {
+    return name;
+  }
+}
+
+function generateDocComment(summary, description, param) {
+  if (summary !== undefined) {
+    if (description !== undefined) {
+      return `// ` + summary + `\n// ` + description + `\n`;
+    } else {
+      return `// ` + summary + `\n`;
+    }
+  } else if (description !== undefined) {
+    return `// ` + description + `\n`;
+  } else {
+    return "";
+  }
+}
+
+function generateDocString(summary, description, param) {
+  let content = summary !== undefined ? (
+      description !== undefined ? (
+          summary === description ? summary : summary + "\n\n" + description
+        ) : summary
+    ) : (
+      description !== undefined ? description : undefined
+    );
+  return Stdlib_Option.getOr(Stdlib_Option.map(content, text => {
+    let lines = text.trim().split("\n").map(prim => prim.trim());
+    let len = lines.length;
+    if (len !== 1) {
+      if (len !== 0) {
+        return "/**\n" + lines.map(l => {
+          if (l === "") {
+            return " *";
+          } else {
+            return ` * ` + l;
+          }
+        }).join("\n") + "\n */\n";
+      } else {
+        return "";
+      }
+    }
+    let line = lines[0];
+    return `/** ` + line + ` */\n`;
+  }), "");
+}
+
+function variantConstructorName(_irType) {
+  while (true) {
+    let irType = _irType;
+    if (typeof irType !== "object") {
+      switch (irType) {
+        case "Boolean" :
+          return "Bool";
+        case "Null" :
+          return "Null";
+        case "Unknown" :
+          return "Unknown";
+      }
+    } else {
+      switch (irType.TAG) {
+        case "String" :
+          return "String";
+        case "Number" :
+          return "Float";
+        case "Integer" :
+          return "Int";
+        case "Array" :
+          return "Array";
+        case "Object" :
+          return "Object";
+        case "Literal" :
+          let s = irType._0;
+          if (typeof s !== "object") {
+            return "Null";
+          }
+          switch (s.TAG) {
+            case "StringLiteral" :
+              return JsConvertCase.toPascalCase(s._0);
+            case "NumberLiteral" :
+              return "Number";
+            case "BooleanLiteral" :
+              return "Bool";
+          }
+        case "Union" :
+          return "Union";
+        case "Intersection" :
+          return "Intersection";
+        case "Reference" :
+          let ref = irType._0;
+          return JsConvertCase.toPascalCase(ref.includes("/") ? Stdlib_Option.getOr(ref.split("/")[ref.split("/").length - 1 | 0], "Ref") : ref);
+        case "Option" :
+          _irType = irType._0;
+          continue;
+      }
+    }
+  };
+}
+
+function deduplicateNames(names) {
+  let counts = {};
+  let result = [];
+  names.forEach(name => {
+    let count = Stdlib_Option.getOr(counts[name], 0);
+    counts[name] = count + 1 | 0;
+  });
+  let seen = {};
+  names.forEach(name => {
+    let total = Stdlib_Option.getOr(counts[name], 1);
+    if (total > 1) {
+      let idx = Stdlib_Option.getOr(seen[name], 0) + 1 | 0;
+      seen[name] = idx;
+      result.push(name + idx.toString());
+      return;
+    }
+    result.push(name);
+  });
+  return result;
+}
+
+let fetchTypeSignature = "(~url: string, ~method_: string, ~body: option<JSON.t>) => Promise.t<JSON.t>";
+
+export {
+  sanitizeIdentifier,
+  generateTypeName,
+  generateOperationName,
+  escapeString,
+  generateFileHeader,
+  indent,
+  trimMargin,
+  rescriptKeywords,
+  escapeKeyword,
+  generateDocComment,
+  generateDocString,
+  fetchTypeSignature,
+  variantConstructorName,
+  deduplicateNames,
+}
+/* js-convert-case Not a pure module */

package/lib/es6/src/core/DocOverride.mjs

@@ -0,0 +1,399 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Fs from "fs";
+import * as Js_string from "@rescript/runtime/lib/es6/Js_string.js";
+import * as FileSystem from "./FileSystem.mjs";
+import * as CodegenUtils from "./CodegenUtils.mjs";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as JsConvertCase from "js-convert-case";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+
+function generateEndpointHash(endpoint) {
+  let parts = [
+    endpoint.path,
+    endpoint.method,
+    Stdlib_Option.getOr(endpoint.operationId, ""),
+    Stdlib_Option.getOr(endpoint.summary, ""),
+    Stdlib_Option.getOr(endpoint.description, "")
+  ];
+  let combined = parts.join("|");
+  return Stdlib_Array.reduce(combined.split(""), 0, (acc, char) => {
+    let code = Js_string.charCodeAt(0, char) | 0;
+    return (((acc << 5) - acc | 0) + code | 0) % 2147483647;
+  }).toString(16);
+}
+
+function extractCodeBlock(markdown) {
+  let parts = markdown.split("```");
+  if (parts.length < 3) {
+    return;
+  }
+  let content = parts[1];
+  if (content === undefined) {
+    return;
+  }
+  let trimmed = content.trim();
+  if (trimmed === "" || trimmed === "<!-- Empty - no override -->") {
+    return;
+  } else {
+    return trimmed;
+  }
+}
+
+function parseOverrideMarkdown(content) {
+  let parts = content.split("---");
+  if (parts.length < 3) {
+    return;
+  }
+  let frontmatter = Stdlib_Option.getOr(parts[1], "");
+  let body = parts.slice(2, parts.length).join("---").trim();
+  let lines = frontmatter.split("\n").map(prim => prim.trim());
+  let metadata_endpoint = Stdlib_Option.getOr(Stdlib_Option.map(lines.find(l => l.startsWith("endpoint:")), l => {
+    let parts = l.split(":");
+    return parts.slice(1, parts.length).join(":").trim();
+  }), "");
+  let metadata_method = Stdlib_Option.getOr(Stdlib_Option.map(lines.find(l => l.startsWith("method:")), l => Stdlib_Option.getOr(l.split(":")[1], "").trim()), "");
+  let metadata_hash = Stdlib_Option.getOr(Stdlib_Option.map(lines.find(l => l.startsWith("hash:")), l => Stdlib_Option.getOr(l.split(":")[1], "").trim()), "");
+  let metadata_host = Stdlib_Option.flatMap(lines.find(l => l.startsWith("host:")), l => {
+    let parts = l.split(":");
+    return parts.slice(1, parts.length).join(":").trim();
+  });
+  let metadata_version = Stdlib_Option.flatMap(lines.find(l => l.startsWith("version:")), l => Stdlib_Option.map(l.split(":")[1], prim => prim.trim()));
+  let metadata_operationId = Stdlib_Option.flatMap(lines.find(l => l.startsWith("operationId:")), l => Stdlib_Option.map(l.split(":")[1], prim => prim.trim()));
+  let metadata = {
+    endpoint: metadata_endpoint,
+    method: metadata_method,
+    hash: metadata_hash,
+    host: metadata_host,
+    version: metadata_version,
+    operationId: metadata_operationId
+  };
+  let parts$1 = Stdlib_Option.getOr(body.split("## Override")[0], "").split("## Default Description");
+  let defaultDescSection = parts$1.slice(1, parts$1.length).join("## Default Description").trim();
+  let parts$2 = body.split("## Override");
+  let overrideSection = parts$2.slice(1, parts$2.length).join("## Override");
+  let overrideDesc = extractCodeBlock(overrideSection);
+  let hasOverride = Stdlib_Option.isSome(overrideDesc);
+  return {
+    metadata: metadata,
+    defaultDescription: defaultDescSection,
+    overrideDescription: overrideDesc,
+    hasOverride: hasOverride
+  };
+}
+
+function generateOverrideMarkdown(endpoint, host, version, param) {
+  let hash = generateEndpointHash(endpoint);
+  let operationName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method);
+  let match = endpoint.summary;
+  let match$1 = endpoint.description;
+  let defaultDesc = match !== undefined ? (
+      match$1 !== undefined && match !== match$1 ? match + "\n\n" + match$1 : match
+    ) : (
+      match$1 !== undefined ? match$1 : "No description provided."
+    );
+  let metadata = [
+    "---",
+    `endpoint: ` + endpoint.path,
+    `method: ` + endpoint.method.toUpperCase(),
+    `hash: ` + hash
+  ].concat(Stdlib_Array.filterMap([
+    Stdlib_Option.map(host, h => `host: ` + h),
+    Stdlib_Option.map(version, v => `version: ` + v),
+    Stdlib_Option.map(endpoint.operationId, id => `operationId: ` + id),
+    "---"
+  ], x => x));
+  let content = `
+    |` + metadata.join("\n") + `
+    |
+    |# ` + Stdlib_Option.getOr(endpoint.summary, endpoint.path) + `
+    |
+    |**Path**: \`` + endpoint.path + `\`  
+    |**Method**: \`` + endpoint.method.toUpperCase() + `\`  
+    |**Operation**: \`` + operationName + `\`
+    |
+    |## Default Description
+    |
+    |` + defaultDesc + `
+    |
+    |## Override
+    |
+    |Add your custom documentation here. If this code block is empty, the default description will be used.
+    |
+    |\`\`\`
+    |<!-- Empty - no override -->
+    |\`\`\`
+    |`;
+  return CodegenUtils.trimMargin(content, undefined);
+}
+
+function validateOverride(override, currentHash) {
+  if (override.metadata.hash === currentHash) {
+    return "Valid";
+  } else {
+    return {
+      TAG: "HashMismatch",
+      expected: currentHash,
+      found: override.metadata.hash
+    };
+  }
+}
+
+function readOverrideWithValidation(overrideDir, moduleName, functionName, currentHash) {
+  let filePath = FileSystem.makePath(FileSystem.makePath(overrideDir, moduleName), functionName + ".md");
+  if (!Fs.existsSync(filePath)) {
+    return "NoOverride";
+  }
+  try {
+    let content = Fs.readFileSync(filePath, {
+      encoding: "utf8"
+    });
+    let parsed = parseOverrideMarkdown(content);
+    if (parsed === undefined) {
+      return {
+        TAG: "FileError",
+        _0: "Failed to parse markdown file"
+      };
+    }
+    if (!parsed.hasOverride) {
+      return "NoOverride";
+    }
+    let msg = validateOverride(parsed, currentHash);
+    if (typeof msg !== "object") {
+      if (msg !== "Valid") {
+        return {
+          TAG: "FileError",
+          _0: "Override file missing"
+        };
+      }
+      let desc = parsed.overrideDescription;
+      if (desc !== undefined) {
+        return {
+          TAG: "ValidOverride",
+          _0: desc
+        };
+      } else {
+        return "NoOverride";
+      }
+    } else {
+      if (msg.TAG !== "HashMismatch") {
+        return {
+          TAG: "FileError",
+          _0: msg._0
+        };
+      }
+      let desc$1 = parsed.overrideDescription;
+      if (desc$1 !== undefined) {
+        return {
+          TAG: "InvalidHash",
+          override: desc$1,
+          expected: msg.expected,
+          found: msg.found
+        };
+      } else {
+        return "NoOverride";
+      }
+    }
+  } catch (raw_err) {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    if (err.RE_EXN_ID === "JsExn") {
+      return {
+        TAG: "FileError",
+        _0: Stdlib_Option.getOr(Stdlib_JsExn.message(err._1), "Unknown error")
+      };
+    } else {
+      return {
+        TAG: "FileError",
+        _0: "Unknown error reading file"
+      };
+    }
+  }
+}
+
+function readOverride(overrideDir, moduleName, functionName) {
+  let filePath = FileSystem.makePath(FileSystem.makePath(overrideDir, moduleName), functionName + ".md");
+  if (!Fs.existsSync(filePath)) {
+    return;
+  }
+  try {
+    let content = Fs.readFileSync(filePath, {
+      encoding: "utf8"
+    });
+    let parsed = parseOverrideMarkdown(content);
+    if (parsed !== undefined) {
+      return parsed.overrideDescription;
+    } else {
+      return;
+    }
+  } catch (exn) {
+    return;
+  }
+}
+
+function isFileCustomized(filePath) {
+  if (!Fs.existsSync(filePath)) {
+    return false;
+  }
+  try {
+    let content = Fs.readFileSync(filePath, {
+      encoding: "utf8"
+    });
+    let parsed = parseOverrideMarkdown(content);
+    if (parsed !== undefined) {
+      return parsed.hasOverride;
+    } else {
+      return false;
+    }
+  } catch (exn) {
+    return false;
+  }
+}
+
+function generateOverrideFiles(spec, endpoints, outputDir, host, groupByTagOpt, param) {
+  let groupByTag = groupByTagOpt !== undefined ? groupByTagOpt : true;
+  let version = spec.info.version;
+  let hostUrl = host !== undefined ? host : spec.info.description;
+  return Stdlib_Array.keepSome(endpoints.map(endpoint => {
+    let moduleName;
+    if (groupByTag) {
+      let tags = endpoint.tags;
+      moduleName = tags !== undefined ? Stdlib_Option.getOr(tags[0], "Default") : "Default";
+    } else {
+      moduleName = "API";
+    }
+    let functionName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method);
+    let modulePath = FileSystem.makePath(outputDir, JsConvertCase.toPascalCase(moduleName));
+    let filePath = FileSystem.makePath(modulePath, functionName + ".md");
+    if (isFileCustomized(filePath)) {
+      console.log(`ℹ️  Skipping ` + moduleName + `/` + functionName + ` - file already customized`);
+      return;
+    }
+    let content = generateOverrideMarkdown(endpoint, hostUrl, version, undefined);
+    return {
+      path: filePath,
+      content: content
+    };
+  }));
+}
+
+function generateOverrideReadme(host, version, param) {
+  let hostInfo = Stdlib_Option.getOr(host, "Not specified");
+  let versionInfo = Stdlib_Option.getOr(version, "Not specified");
+  return CodegenUtils.trimMargin(`
+    |# API Documentation Overrides
+    |
+    |This directory contains markdown files that allow you to override the auto-generated documentation.
+    |
+    |## Global Information
+    |
+    |- **Host**: ` + hostInfo + `
+    |- **Version**: ` + versionInfo + `
+    |
+    |## Structure
+    |
+    |Each module has its own directory, and each endpoint has its own markdown file:
+    |
+    |\`\`\`
+    |docs/
+    |├── README.md (this file)
+    |├── Account/
+    |│   ├── postBlockingCreate.md
+    |│   ├── postBlockingDelete.md
+    |│   └── ...
+    |├── Notes/
+    |│   ├── postNotesCreate.md
+    |│   └── ...
+    |└── ...
+    |\`\`\`
+    |
+    |## How to Override
+    |
+    |1. Find the endpoint you want to document in its module directory
+    |2. Open the markdown file
+    |3. Edit the code block under the "## Override" section
+    |4. Add your custom documentation (supports markdown)
+    |5. Regenerate the code - your custom documentation will be used instead of the default
+    |
+    |## File Format
+    |
+    |Each file contains:
+    |
+    |### Frontmatter
+    |- \`endpoint\`: The API endpoint path
+    |- \`method\`: HTTP method (GET, POST, etc.)
+    |- \`hash\`: Hash of the endpoint for change detection
+    |- \`host\`: API host URL
+    |- \`version\`: API version
+    |- \`operationId\`: OpenAPI operation ID
+    |
+    |### Default Description
+    |The original description from the OpenAPI spec.
+    |
+    |### Override Section
+    |A code block where you can add your custom documentation. If empty, the default description is used.
+    |
+    |## Example
+    |
+    |\`\`\`markdown
+    |---
+    |endpoint: /blocking/create
+    |method: POST
+    |hash: abc123
+    |host: https://misskey.io
+    |version: 1.0.0
+    |---
+    |
+    |# blocking/create
+    |
+    |**Path**: \`/blocking/create\`
+    |**Method**: \`POST\`
+    |
+    |## Default Description
+    |
+    |No description provided.
+    |
+    |**Credential required**: *Yes* / **Permission**: *write:blocks*
+    |
+    |## Override
+    |
+    |\`\`\`
+    |Create a blocking relationship with another user.
+    |
+    |This endpoint allows you to block a user by their user ID. Once blocked:
+    |- The user will not be able to see your posts
+    |- You will not see their posts in your timeline
+    |- They cannot follow you
+    |
+    |**Parameters:**
+    |- \`userId\`: The ID of the user to block
+    |
+    |**Example:**
+    |\`\`\`typescript
+    |await client.blocking.create({ userId: "user123" })
+    |\`\`\`
+    |\`\`\`
+    |\`\`\`
+    |
+    |## Notes
+    |
+    |- The hash is used to detect if the endpoint has changed in the OpenAPI spec
+    |- If the endpoint changes, you may need to update your override
+    |- Empty override blocks (with just \`<!-- Empty - no override -->\`) are ignored
+    |`, undefined);
+}
+
+export {
+  generateEndpointHash,
+  extractCodeBlock,
+  parseOverrideMarkdown,
+  generateOverrideMarkdown,
+  validateOverride,
+  readOverrideWithValidation,
+  readOverride,
+  isFileCustomized,
+  generateOverrideFiles,
+  generateOverrideReadme,
+}
+/* fs Not a pure module */

package/lib/es6/src/core/FileSystem.d.ts

@@ -0,0 +1,4 @@
+export type fileToWrite = {
+    readonly path: string;
+    readonly content: string;
+};