@f3liz/rescript-autogen-openapi 0.1.0

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 Text from "@std/text";
+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 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, Text.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.mjs

@@ -0,0 +1,78 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Fs from "fs";
+import * as Path from "@std/path";
+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 Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+
+function ensureDir(path) {
+  try {
+    Fs.mkdirSync(Path.dirname(path), {
+      recursive: true
+    });
+    return;
+  } catch (exn) {
+    return;
+  }
+}
+
+function writeFile(file) {
+  try {
+    ensureDir(file.path);
+    Fs.writeFileSync(file.path, file.content, "utf8");
+    return {
+      TAG: "Ok",
+      _0: undefined
+    };
+  } catch (raw_exn) {
+    let exn = Primitive_exceptions.internalToException(raw_exn);
+    if (exn.RE_EXN_ID !== "JsExn") {
+      return {
+        TAG: "Error",
+        _0: `Failed to write file ` + file.path + `: Unknown error`
+      };
+    }
+    let message = Stdlib_Option.getOr(Stdlib_JsExn.message(exn._1), "Unknown error");
+    return {
+      TAG: "Error",
+      _0: `Failed to write file ` + file.path + `: ` + message
+    };
+  }
+}
+
+function writeFiles(files) {
+  let successes = [];
+  let errors = [];
+  files.forEach(file => {
+    let err = writeFile(file);
+    if (err.TAG === "Ok") {
+      successes.push(file.path);
+      return;
+    }
+    errors.push(err._0);
+  });
+  if (errors.length !== 0) {
+    return {
+      TAG: "Error",
+      _0: errors
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: successes
+    };
+  }
+}
+
+function makePath(baseDir, filename) {
+  return Path.join(baseDir, filename);
+}
+
+export {
+  ensureDir,
+  writeFile,
+  writeFiles,
+  makePath,
+}
+/* fs Not a pure module */

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

@@ -0,0 +1,201 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function string(min, max, pattern, param) {
+  return {
+    minLength: min,
+    maxLength: max,
+    pattern: pattern
+  };
+}
+
+function number(min, max, multipleOf, param) {
+  return {
+    minimum: min,
+    maximum: max,
+    multipleOf: multipleOf
+  };
+}
+
+function array(min, max, uniqueOpt, param) {
+  let unique = uniqueOpt !== undefined ? uniqueOpt : false;
+  return {
+    minItems: min,
+    maxItems: max,
+    uniqueItems: unique
+  };
+}
+
+let Constraints = {
+  string: string,
+  number: number,
+  array: array
+};
+
+function string$1(min, max, pattern, param) {
+  return {
+    TAG: "String",
+    constraints: {
+      minLength: min,
+      maxLength: max,
+      pattern: pattern
+    }
+  };
+}
+
+function number$1(min, max, multipleOf, param) {
+  return {
+    TAG: "Number",
+    constraints: {
+      minimum: min,
+      maximum: max,
+      multipleOf: multipleOf
+    }
+  };
+}
+
+function int(min, max, multipleOf, param) {
+  return {
+    TAG: "Integer",
+    constraints: {
+      minimum: min,
+      maximum: max,
+      multipleOf: multipleOf
+    }
+  };
+}
+
+function array$1(items, min, max, uniqueOpt, param) {
+  let unique = uniqueOpt !== undefined ? uniqueOpt : false;
+  return {
+    TAG: "Array",
+    items: items,
+    constraints: array(min, max, unique, undefined)
+  };
+}
+
+function object_(props, additional, param) {
+  return {
+    TAG: "Object",
+    properties: props,
+    additionalProperties: additional
+  };
+}
+
+function union(types) {
+  return {
+    TAG: "Union",
+    _0: types
+  };
+}
+
+function intersection(types) {
+  return {
+    TAG: "Intersection",
+    _0: types
+  };
+}
+
+function ref(refPath) {
+  return {
+    TAG: "Reference",
+    _0: refPath
+  };
+}
+
+function option(type_) {
+  return {
+    TAG: "Option",
+    _0: type_
+  };
+}
+
+function stringLit(s) {
+  return {
+    TAG: "Literal",
+    _0: {
+      TAG: "StringLiteral",
+      _0: s
+    }
+  };
+}
+
+function numberLit(n) {
+  return {
+    TAG: "Literal",
+    _0: {
+      TAG: "NumberLiteral",
+      _0: n
+    }
+  };
+}
+
+function boolLit(b) {
+  return {
+    TAG: "Literal",
+    _0: {
+      TAG: "BooleanLiteral",
+      _0: b
+    }
+  };
+}
+
+function prop(name, type_, requiredOpt, param) {
+  let required = requiredOpt !== undefined ? requiredOpt : true;
+  return [
+    name,
+    type_,
+    required
+  ];
+}
+
+function optProp(name, type_) {
+  return [
+    name,
+    type_,
+    false
+  ];
+}
+
+function named(name, description, type_) {
+  return {
+    name: name,
+    description: description,
+    type_: type_
+  };
+}
+
+let bool = "Boolean";
+
+let $$null = "Null";
+
+let unknown = "Unknown";
+
+let nullLit = {
+  TAG: "Literal",
+  _0: "NullLiteral"
+};
+
+export {
+  Constraints,
+  string$1 as string,
+  number$1 as number,
+  int,
+  bool,
+  $$null,
+  unknown,
+  array$1 as array,
+  object_,
+  union,
+  intersection,
+  ref,
+  option,
+  stringLit,
+  numberLit,
+  boolLit,
+  nullLit,
+  prop,
+  optProp,
+  named,
+}
+/* No side effect */