@f3liz/rescript-autogen-openapi 0.5.4 → 0.6.0

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

@@ -0,0 +1,43 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Module from "module";
+
+let _require = Module.createRequire(import.meta.url);
+
+let handlebars = _require("handlebars");
+
+let convert = _require("js-convert-case");
+
+let _render = ((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);
+
+function render(template, data) {
+  return _render(template, data);
+}
+
+export {
+  _require,
+  _render,
+  render,
+}
+/* _require Not a pure module */

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

@@ -1,5 +1,8 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Templates from "./Templates.mjs";
+import * as Handlebars from "../bindings/Handlebars.mjs";
+import * as Stdlib_Null from "@rescript/runtime/lib/es6/Stdlib_Null.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as JsConvertCase from "js-convert-case";
 
@@ -91,12 +94,9 @@ function escapeRegexPattern(str) {
 }
 
 function generateFileHeader(description) {
-  return `// ` + description + `
-// Generated by @f3liz/rescript-autogen-openapi
-// DO NOT EDIT - This file is auto-generated
-
-S.enableJson()
-`;
+  return Handlebars.render(Templates.fileHeader, {
+    description: description
+  });
 }
 
 function indent(code, level) {
@@ -110,18 +110,6 @@ function indent(code, level) {
   }).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",
@@ -185,17 +173,10 @@ function escapeKeyword(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 "";
-  }
+  return Handlebars.render(Templates.docComment, {
+    summary: Stdlib_Null.fromOption(summary),
+    description: Stdlib_Null.fromOption(description)
+  });
 }
 
 function generateDocString(summary, description, param) {
@@ -211,19 +192,17 @@ function generateDocString(summary, description, param) {
     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";
+        return Handlebars.render(Templates.docCommentMulti, {
+          lines: lines
+        });
       } else {
         return "";
       }
     }
     let line = lines[0];
-    return `/** ` + line + ` */\n`;
+    return Handlebars.render(Templates.docCommentSingle, {
+      content: line
+    });
   }), "");
 }
 
@@ -310,7 +289,6 @@ export {
   escapeRegexPattern,
   generateFileHeader,
   indent,
-  trimMargin,
   rescriptKeywords,
   escapeKeyword,
   generateDocComment,
@@ -319,4 +297,4 @@ export {
   variantConstructorName,
   deduplicateNames,
 }
-/* js-convert-case Not a pure module */
+/* Handlebars Not a pure module */

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

@@ -2,7 +2,9 @@
 
 import * as Fs from "fs";
 import * as Js_string from "@rescript/runtime/lib/es6/Js_string.js";
+import * as Templates from "./Templates.mjs";
 import * as FileSystem from "./FileSystem.mjs";
+import * as Handlebars from "../bindings/Handlebars.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";
@@ -105,28 +107,14 @@ function generateOverrideMarkdown(endpoint, host, version, param) {
     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);
+  return Handlebars.render(Templates.overrideMarkdown, {
+    metadataBlock: metadata.join("\n"),
+    title: Stdlib_Option.getOr(endpoint.summary, endpoint.path),
+    path: endpoint.path,
+    methodUpper: endpoint.method.toUpperCase(),
+    operationName: operationName,
+    defaultDesc: defaultDesc
+  });
 }
 
 function validateOverride(override, currentHash) {
@@ -281,107 +269,10 @@ function generateOverrideFiles(spec, endpoints, outputDir, host, groupByTagOpt,
 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);
+  return Handlebars.render(Templates.overrideReadme, {
+    hostInfo: hostInfo,
+    versionInfo: versionInfo
+  });
 }
 
 export {

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

@@ -0,0 +1,341 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let fileHeader = `// {{{description}}}
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT - This file is auto-generated
+
+S.enableJson()
+`;
+
+let docCommentSingle = `/** {{{content}}} */
+`;
+
+let docCommentMulti = `/**
+{{#each lines}}{{{this}}}
+{{/each}}*/
+`;
+
+let docComment = `{{#if summary}}// {{{summary}}}
+{{/if}}{{#if description}}// {{{description}}}
+{{/if}}`;
+
+let endpointFunction = `{{{docComment}}}let {{{functionName}}} = ({{{bodyParam}}}{{{paramSep}}}~fetch: {{{fetchTypeSignature}}}): promise<{{{functionName}}}Response> => {
+{{{bodyValueConversion}}}
+  fetch(
+    ~url="{{{path}}}",
+    ~method_="{{{methodUpper}}}",
+    ~body={{{bodyArg}}},
+  )->Promise.then(response => {
+{{{responseHandling}}}
+    ->Promise.resolve
+  })
+}`;
+
+let moduleWrapped = `{{{header}}}
+
+module {{{moduleName}}} = {
+{{{body}}}
+}`;
+
+let moduleUnwrapped = `{{{header}}}
+
+{{{body}}}`;
+
+let indexModule = `{{{header}}}
+
+module {{{moduleName}}} = {
+{{#each tags}}  module {{{modulePascal}}} = {{{modulePascal}}}
+{{/each}}}`;
+
+let combinedModule = `{{{header}}}
+
+{{{shared}}}
+
+{{{extension}}}`;
+
+let clientType = `type client = {
+  baseUrl: string,
+  token: option<string>,
+  fetch: {{{fetchTypeSignature}}},
+}`;
+
+let connectFunction = `/** Create a client for {{{title}}} */
+let connect = (~baseUrl: string, ~token: option<string>=?, ~fetch: {{{fetchTypeSignature}}}, ()): client => {
+  baseUrl,
+  token,
+  fetch,
+}`;
+
+let wrapperFunction = `{{{docComment}}}  {{{signature}}}: promise<{{{generatedModuleName}}}.{{{operationName}}}Response> => 
+    {{{generatedModuleName}}}.{{{operationName}}}({{{callArguments}}}~fetch=client.fetch)`;
+
+let wrapperFile = `// Generated thin wrapper
+
+{{{clientTypeCode}}}
+
+{{{connectFunctionCode}}}
+
+{{{modulesCode}}}`;
+
+let methodSignature = `{{{docLines}}}
+  {{{functionName}}}({{{params}}}): Promise<{{{responsePascalName}}}Response>;`;
+
+let moduleDts = `// TypeScript definitions for {{{moduleName}}}
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT
+
+import { MisskeyClient } from './index';
+import * as ComponentSchemas from './ComponentSchemas';
+
+{{{interfaces}}}
+
+export interface {{{moduleName}}}Module {
+{{{methodSignatures}}}
+}
+
+export const {{{moduleName}}}: {{{moduleName}}}Module;`;
+
+let componentSchemasDts = `// TypeScript definitions for ComponentSchemas
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT
+
+{{{content}}}`;
+
+let indexDts = `// TypeScript definitions
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT
+
+{{#each modules}}{{{importLine}}}
+{{/each}}
+export class MisskeyClient {
+  constructor(baseUrl: string, token?: string);
+  readonly baseUrl: string;
+  readonly token?: string;
+}
+
+{{#each modules}}{{{exportLine}}}
+{{/each}}`;
+
+let wrapperMjsMethod = `  async {{{functionName}}}(client{{{requestArg}}}) {
+    return {{{moduleName}}}.{{{functionName}}}({
+      {{{bodyArg}}}fetch: (url, method, body) => client._fetch(url, method, body)
+    });
+  },`;
+
+let wrapperMjsNamespace = `export const {{{moduleName}}} = {
+{{{methods}}}
+};`;
+
+let wrapperMjs = `// Generated wrapper
+{{#each tags}}{{{importLine}}}
+{{/each}}
+{{{clientCode}}}
+
+{{#each tags}}{{{namespace}}}
+
+{{/each}}`;
+
+let wrapperDtsFunction = `{{{docComment}}}  export function {{{functionName}}}(client: MisskeyClient{{{requestParam}}}): Promise<{{{pascalName}}}Response>;`;
+
+let wrapperDtsNamespace = `export namespace {{{moduleName}}} {
+{{{functions}}}
+}`;
+
+let wrapperDts = `// Generated TypeScript definitions for wrapper
+{{#each tags}}{{{importBlock}}}
+{{/each}}
+export class MisskeyClient {
+  constructor(baseUrl: string, token?: string);
+  readonly baseUrl: string;
+  readonly token?: string;
+}
+
+{{#each tags}}{{{namespace}}}
+
+{{/each}}`;
+
+let mergeReport = `# Merge Report: {{{baseName}}} + {{{forkName}}}
+
+## Shared Code
+
+- **Shared Endpoints**: {{{sharedEndpoints}}}
+- **Shared Schemas**: {{{sharedSchemas}}}
+
+## {{{forkName}}} Extensions
+
+- **Extension Endpoints**: {{{extensionEndpoints}}}
+- **Extension Schemas**: {{{extensionSchemas}}}
+
+## Summary
+
+The shared base contains {{{sharedEndpoints}}} endpoints and {{{sharedSchemas}}} schemas.
+
+{{{forkName}}} adds {{{extensionEndpoints}}} endpoints and {{{extensionSchemas}}} schemas.
+
+---
+*Generated on {{{timestamp}}}*`;
+
+let endpointModule = `{{{docComment}}}module {{{moduleName}}} = {
+{{{schemasCode}}}
+
+  let endpoint = "{{{path}}}"
+  let method = #{{{methodStr}}}
+}`;
+
+let overrideMarkdown = `{{{metadataBlock}}}
+
+# {{{title}}}
+
+**Path**: \`{{{path}}}\`  
+**Method**: \`{{{methodUpper}}}\`  
+**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 -->
+\`\`\``;
+
+let overrideReadme = `# 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`;
+
+let componentSchemaModule = `{{{docComment}}}module {{{moduleName}}} = {
+{{{extractedBlock}}}{{{typeKeyword}}} = {{{typeCode}}}
+  let schema = {{{schemaCode}}}
+}`;
+
+export {
+  fileHeader,
+  docCommentSingle,
+  docCommentMulti,
+  docComment,
+  endpointFunction,
+  moduleWrapped,
+  moduleUnwrapped,
+  indexModule,
+  combinedModule,
+  clientType,
+  connectFunction,
+  wrapperFunction,
+  wrapperFile,
+  methodSignature,
+  moduleDts,
+  componentSchemasDts,
+  indexDts,
+  wrapperMjsMethod,
+  wrapperMjsNamespace,
+  wrapperMjs,
+  wrapperDtsFunction,
+  wrapperDtsNamespace,
+  wrapperDts,
+  mergeReport,
+  endpointModule,
+  overrideMarkdown,
+  overrideReadme,
+  componentSchemaModule,
+}
+/* No side effect */

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

@@ -2,7 +2,9 @@
 
 import * as Pipeline from "../core/Pipeline.mjs";
 import * as Toposort from "../bindings/Toposort.mjs";
+import * as Templates from "../core/Templates.mjs";
 import * as FileSystem from "../core/FileSystem.mjs";
+import * as Handlebars from "../bindings/Handlebars.mjs";
 import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
 import * as CodegenUtils from "../core/CodegenUtils.mjs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
@@ -187,10 +189,14 @@ function generate(spec, outputDir) {
     let extractedBlock = extractedTypeDefs.length !== 0 ? extractedTypeDefs.join("\n") + "\n" : "";
     let typeKeyword = isSelfRef ? "type rec t" : "type t";
     let finalSchemaCode = isSelfRef ? `S.recursive("` + schema.name + `", schema => ` + schemaCode + `)` : schemaCode;
-    return docComment + `module ` + JsConvertCase.toPascalCase(schema.name) + ` = {
-` + extractedBlock + `  ` + typeKeyword + ` = ` + typeCode + `
-  let schema = ` + finalSchemaCode + `
-}`;
+    return Handlebars.render(Templates.componentSchemaModule, {
+      docComment: docComment,
+      moduleName: JsConvertCase.toPascalCase(schema.name),
+      extractedBlock: extractedBlock,
+      typeKeyword: `  ` + typeKeyword,
+      typeCode: typeCode,
+      schemaCode: finalSchemaCode
+    });
   });
   let fileHeader = CodegenUtils.generateFileHeader("Shared component schemas");
   let fileContent = fileHeader + `\n\n` + moduleCodes.join("\n\n");