@f3liz/rescript-autogen-openapi 0.5.4 → 0.7.0

package/lib/es6/src/generators/TypeScriptWrapperGenerator.mjs

@@ -1,74 +1,51 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Pipeline from "../core/Pipeline.mjs";
+import * as Templates from "../core/Templates.mjs";
 import * as FileSystem from "../core/FileSystem.mjs";
+import * as Handlebars from "../bindings/Handlebars.mjs";
 import * as CodegenUtils from "../core/CodegenUtils.mjs";
 import * as OpenAPIParser from "../core/OpenAPIParser.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as JsConvertCase from "js-convert-case";
 
-let misskeyClientJsCode = CodegenUtils.trimMargin(`
-  |export class MisskeyClient {
-  |  constructor(baseUrl, token) {
-  |    this.baseUrl = baseUrl;
-  |    this.token = token;
-  |  }
-  |
-  |  async _fetch(url, method, body) {
-  |    const headers = { 'Content-Type': 'application/json' };
-  |    if (this.token) {
-  |      headers['Authorization'] = \`Bearer \${this.token}\`;
-  |    }
-  |    const response = await fetch(this.baseUrl + url, {
-  |      method,
-  |      headers,
-  |      body: body ? JSON.stringify(body) : undefined,
-  |    });
-  |    return response.json();
-  |  }
-  |}`, undefined);
+let body = "export class MisskeyClient {\n  constructor(baseUrl, token) {\n    this.baseUrl = baseUrl;\n    this.token = token;\n  }\n\n  async _fetch(url, method, body) {\n    const headers = { 'Content-Type': 'application/json' };\n    if (this.token) {\n      headers['Authorization'] = \x60Bearer \x24{this.token}\x60;\n    }\n    const response = await fetch(this.baseUrl + url, {\n      method,\n      headers,\n      body: body ? JSON.stringify(body) : undefined,\n    });\n    return response.json();\n  }\n}";
 
 function generateWrapperMjs(endpoints, generatedModulePath) {
   let endpointsByTag = OpenAPIParser.groupByTag(endpoints);
   let tags = Object.keys(endpointsByTag);
-  let imports = tags.map(tag => {
-    let moduleName = JsConvertCase.toPascalCase(tag);
-    return `import * as ` + moduleName + ` from '` + generatedModulePath + `/` + moduleName + `.mjs';`;
-  }).join("\n");
-  let wrappers = tags.map(tag => {
+  let tagData = tags.map(tag => {
     let moduleName = JsConvertCase.toPascalCase(tag);
+    let importLine = `import * as ` + moduleName + ` from '` + generatedModulePath + `/` + moduleName + `.mjs';`;
     let methods = Stdlib_Option.getOr(endpointsByTag[tag], []).map(endpoint => {
       let functionName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method);
       let hasRequestBody = Stdlib_Option.isSome(endpoint.requestBody);
-      let bodyArg = hasRequestBody ? "body: request, " : "";
-      return `
-            |  async ` + functionName + `(client` + (
-        hasRequestBody ? ", request" : ""
-      ) + `) {
-            |    return ` + moduleName + `.` + functionName + `({
-            |      ` + bodyArg + `fetch: (url, method, body) => client._fetch(url, method, body)
-            |    });
-            |  },`;
+      return Handlebars.render(Templates.wrapperMjsMethod, {
+        functionName: functionName,
+        moduleName: moduleName,
+        requestArg: hasRequestBody ? ", request" : "",
+        bodyArg: hasRequestBody ? "body: request, " : ""
+      });
     }).join("\n");
-    return `
-        |export const ` + moduleName + ` = {
-        |` + methods + `
-        |};`;
-  }).join("\n\n");
-  return CodegenUtils.trimMargin(`
-    |// Generated wrapper
-    |` + imports + `
-    |
-    |` + misskeyClientJsCode + `
-    |
-    |` + wrappers + `
-    |`, undefined);
+    let namespace = Handlebars.render(Templates.wrapperMjsNamespace, {
+      moduleName: moduleName,
+      methods: methods
+    });
+    return {
+      importLine: importLine,
+      namespace: namespace
+    };
+  });
+  return Handlebars.render(Templates.wrapperMjs, {
+    tags: tagData,
+    clientCode: body
+  });
 }
 
 function generateWrapperDts(endpoints) {
   let endpointsByTag = OpenAPIParser.groupByTag(endpoints);
   let tags = Object.keys(endpointsByTag);
-  let imports = tags.map(tag => {
+  let tagData = tags.map(tag => {
     let moduleName = JsConvertCase.toPascalCase(tag);
     let typesToImport = Stdlib_Option.getOr(endpointsByTag[tag], []).flatMap(endpoint => {
       let pascalName = JsConvertCase.toPascalCase(CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method));
@@ -81,45 +58,62 @@ function generateWrapperDts(endpoints) {
         return [`  ` + pascalName + `Response,`];
       }
     }).join("\n");
-    return `import type {
-` + typesToImport + `
-} from '../types/` + moduleName + `.d.ts';`;
-  }).join("\n");
-  let namespaces = tags.map(tag => {
-    let moduleName = JsConvertCase.toPascalCase(tag);
+    let importBlock = `import type {\n` + typesToImport + `\n} from '../types/` + moduleName + `.d.ts';`;
     let functions = Stdlib_Option.getOr(endpointsByTag[tag], []).map(endpoint => {
       let functionName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method);
       let pascalName = JsConvertCase.toPascalCase(functionName);
-      let docComment = Stdlib_Option.mapOr(endpoint.summary, "", summary => {
-        let descriptionPart = Stdlib_Option.mapOr(endpoint.description, "", description => {
-          if (description === summary) {
-            return "";
+      let match = endpoint.summary;
+      let match$1 = endpoint.description;
+      let docComment;
+      if (match !== undefined) {
+        if (match$1 !== undefined) {
+          if (match === match$1) {
+            docComment = `  /** ` + match + ` */\n`;
+          } else {
+            let descLines = match$1.split("\n").map(line => {
+              if (line === "") {
+                return "   *";
+              } else {
+                return `   * ` + line;
+              }
+            });
+            docComment = `  /**\n   * ` + match + `\n   *\n` + descLines.join("\n") + `\n   */\n`;
+          }
+        } else {
+          docComment = `  /** ` + match + ` */\n`;
+        }
+      } else if (match$1 !== undefined) {
+        let lines = match$1.split("\n").map(line => {
+          if (line === "") {
+            return "   *";
           } else {
-            return " - " + description;
+            return `   * ` + line;
           }
         });
-        return `  /** ` + summary + descriptionPart + ` */\n`;
-      });
+        docComment = `  /**\n` + lines.join("\n") + `\n   */\n`;
+      } else {
+        docComment = "";
+      }
       let requestParam = Stdlib_Option.isSome(endpoint.requestBody) ? `, request: ` + pascalName + `Request` : "";
-      return docComment + `  export function ` + functionName + `(client: MisskeyClient` + requestParam + `): Promise<` + pascalName + `Response>;`;
+      return Handlebars.render(Templates.wrapperDtsFunction, {
+        docComment: docComment,
+        functionName: functionName,
+        requestParam: requestParam,
+        pascalName: pascalName
+      });
     }).join("\n");
-    return `
-        |export namespace ` + moduleName + ` {
-        |` + functions + `
-        |}`;
-  }).join("\n\n");
-  return CodegenUtils.trimMargin(`
-    |// Generated TypeScript definitions for wrapper
-    |` + imports + `
-    |
-    |export class MisskeyClient {
-    |  constructor(baseUrl: string, token?: string);
-    |  readonly baseUrl: string;
-    |  readonly token?: string;
-    |}
-    |
-    |` + namespaces + `
-    |`, undefined);
+    let namespace = Handlebars.render(Templates.wrapperDtsNamespace, {
+      moduleName: moduleName,
+      functions: functions
+    });
+    return {
+      importBlock: importBlock,
+      namespace: namespace
+    };
+  });
+  return Handlebars.render(Templates.wrapperDts, {
+    tags: tagData
+  });
 }
 
 function generate(endpoints, outputDir, generatedModulePathOpt) {
@@ -136,10 +130,12 @@ function generate(endpoints, outputDir, generatedModulePathOpt) {
   ], []);
 }
 
+let misskeyClientJsCode = body;
+
 export {
   misskeyClientJsCode,
   generateWrapperMjs,
   generateWrapperDts,
   generate,
 }
-/* misskeyClientJsCode Not a pure module */
+/* FileSystem Not a pure module */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f3liz/rescript-autogen-openapi",
-  "version": "0.5.4",
+  "version": "0.7.0",
   "description": "Generate ReScript code with Sury schemas from OpenAPI 3.1 specs. Supports multiple forks with diff/merge capabilities.",
   "keywords": [
     "rescript",
@@ -37,6 +37,7 @@
   "type": "module",
   "dependencies": {
     "@readme/openapi-parser": "^5.5.0",
+    "handlebars": "^4.7.8",
     "js-convert-case": "^4.2.0",
     "pathe": "^2.0.3",
     "toposort": "^2.0.2"

package/src/bindings/Handlebars.res

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// Handlebars.res - Minimal Handlebars binding via %raw
+
+@module("module") external createRequire: string => string => 'a = "createRequire"
+@val @scope("import.meta") external importMetaUrl: string = "url"
+
+let _require = createRequire(importMetaUrl)
+
+// Internal: render with untyped data (JSON.t used as universal type at boundary)
+let _render: (string, JSON.t) => string = {
+  let handlebars: 'a = _require("handlebars")
+  let convert: 'a = _require("js-convert-case")
+
+  %raw(`
+    (function(Handlebars, convert) {
+      var instance = Handlebars.create();
+
+      instance.registerHelper('indent', function(content, level) {
+        if (typeof content !== 'string') return '';
+        var spaces = '  '.repeat(typeof level === 'number' ? level : 1);
+        return content.split('\n').map(function(line) {
+          return line.trim() === '' ? '' : spaces + line;
+        }).join('\n');
+      });
+      instance.registerHelper('pascalCase', function(s) { return typeof s === 'string' ? convert.toPascalCase(s) : ''; });
+      instance.registerHelper('camelCase', function(s) { return typeof s === 'string' ? convert.toCamelCase(s) : ''; });
+      instance.registerHelper('upperCase', function(s) { return typeof s === 'string' ? s.toUpperCase() : ''; });
+      instance.registerHelper('eq', function(a, b) { return a === b; });
+      instance.registerHelper('ne', function(a, b) { return a !== b; });
+
+      var cache = {};
+      return function render(template, data) {
+        if (!cache[template]) cache[template] = instance.compile(template, { noEscape: true });
+        return cache[template](data);
+      };
+    })
+  `)(handlebars, convert)
+}
+
+// Public render: accepts any ReScript record/object via Obj.magic
+let render = (template: string, data: 'a): string =>
+  _render(template, Obj.magic(data))

package/src/core/CodegenUtils.res

@@ -115,12 +115,7 @@ let escapeRegexPattern = (str: string): string => {
 
 // Generate file header
 let generateFileHeader = (~description: string): string =>
-  `// ${description}
-// Generated by @f3liz/rescript-autogen-openapi
-// DO NOT EDIT - This file is auto-generated
-
-S.enableJson()
-`
+  Handlebars.render(Templates.fileHeader, {"description": description})
 
 // Indent code
 let indent = (code: string, level: int): string => {
@@ -131,25 +126,6 @@ let indent = (code: string, level: int): string => {
   ->Array.join("\n")
 }
 
-/**
- * Removes leading whitespace followed by a margin prefix from every line of a string.
- * This is useful for writing multiline templates in a more readable way.
- */
-let trimMargin = (text: string, ~marginPrefix="|") => {
-  text
-  ->String.split("\n")
-  ->Array.map(line => {
-    let trimmed = line->String.trimStart
-    if trimmed->String.startsWith(marginPrefix) {
-      trimmed->String.slice(~start=String.length(marginPrefix))
-    } else {
-      line
-    }
-  })
-  ->Array.join("\n")
-  ->String.trim
-}
-
 // ReScript keywords that need to be escaped
 let rescriptKeywords = [
   "and", "as", "assert", "async", "await", "catch", "class", "constraint",
@@ -166,12 +142,10 @@ let escapeKeyword = (name: string): string => rescriptKeywords->Array.includes(n
 
 // Generate documentation comment (single-line comments)
 let generateDocComment = (~summary=?, ~description=?, ()): string =>
-  switch (summary, description) {
-  | (None, None) => ""
-  | (Some(s), None) => `// ${s}\n`
-  | (None, Some(d)) => `// ${d}\n`
-  | (Some(s), Some(d)) => `// ${s}\n// ${d}\n`
-  }
+  Handlebars.render(
+    Templates.docComment,
+    {"summary": summary->Null.fromOption, "description": description->Null.fromOption},
+  )
 
 // Generate DocString comment (multi-line /** ... */ format) from markdown
 let generateDocString = (~summary=?, ~description=?, ()): string => {
@@ -186,8 +160,10 @@ let generateDocString = (~summary=?, ~description=?, ()): string => {
     let lines = text->String.trim->String.split("\n")->Array.map(String.trim)
     switch lines {
     | [] => ""
-    | [line] => `/** ${line} */\n`
-    | lines => "/**\n" ++ lines->Array.map(l => l == "" ? " *" : ` * ${l}`)->Array.join("\n") ++ "\n */\n"
+    | [line] =>
+      Handlebars.render(Templates.docCommentSingle, {"content": line})
+    | lines =>
+      Handlebars.render(Templates.docCommentMulti, {"lines": lines})
     }
   })->Option.getOr("")
 }

package/src/core/DocOverride.res

@@ -183,29 +183,15 @@ let generateOverrideMarkdown = (
     ]->Array.filterMap(x => x)
   )
   
-  let content = `
-    |${Array.join(metadata, "\n")}
-    |
-    |# ${endpoint.summary->Option.getOr(endpoint.path)}
-    |
-    |**Path**: \`${endpoint.path}\`  
-    |**Method**: \`${endpoint.method->String.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 -->
-    |\`\`\`
-    |`
-  
-  content->CodegenUtils.trimMargin
+  Handlebars.render(Templates.overrideMarkdown, {
+      "metadataBlock": Array.join(metadata, "\n"),
+      "title": endpoint.summary->Option.getOr(endpoint.path),
+      "path": endpoint.path,
+      "methodUpper": endpoint.method->String.toUpperCase,
+      "operationName": operationName,
+      "defaultDesc": defaultDesc,
+    },
+  )
 }
 
 // Read override from file system
@@ -390,107 +376,7 @@ let generateOverrideReadme = (~host: option<string>=?, ~version: option<string>=
   let hostInfo = host->Option.getOr("Not specified")
   let versionInfo = version->Option.getOr("Not specified")
   
-  `
-    |# 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
-    |`->CodegenUtils.trimMargin
+  Handlebars.render(Templates.overrideReadme, {"hostInfo": hostInfo, "versionInfo": versionInfo})
 }
 
 // No automatic refresh - users should manually delete outdated files