@f3liz/rescript-autogen-openapi 0.1.0

package/rescript.json

@@ -0,0 +1,20 @@
+{
+  "name": "@f3liz/rescript-autogen-openapi",
+  "sources": [
+    {
+      "dir": "src",
+      "subdirs": true
+    }
+  ],
+  "package-specs": [
+    {
+      "module": "esmodule",
+      "in-source": false
+    }
+  ],
+  "suffix": ".mjs",
+  "dependencies": [],
+  "warnings": {
+    "number": "-44-102"
+  }
+}

package/src/Codegen.res

@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// Codegen.res - Main code generation orchestrator (DOP refactored)
+open Types
+
+// Promise bindings
+@val external promiseAll: array<promise<'a>> => promise<array<'a>> = "Promise.all"
+
+// Generate code from a single spec (pure - returns data)
+let generateSingleSpecPure = (~spec: openAPISpec, ~config: generationConfig): result<Pipeline.t, codegenError> => {
+  try {
+    let targets = config.targets->Option.getOr(Config.defaultTargets())
+    let allEndpoints = OpenAPIParser.getAllEndpoints(spec)
+    let endpoints = switch config.includeTags {
+    | None => allEndpoints
+    | Some(includeTags) => OpenAPIParser.filterByTags(~endpoints=allEndpoints, ~includeTags, ~excludeTags=config.excludeTags->Option.getOr([]))
+    }
+    
+    let baseOutput = targets.rescriptApi 
+      ? Pipeline.combine([
+          ComponentSchemaGenerator.generate(~spec, ~outputDir=config.outputDir),
+          config.modulePerTag
+            ? ModuleGenerator.generateTagModuleFiles(
+                ~endpoints,
+                ~outputDir=config.outputDir,
+                ~overrideDir=?config.docOverrideDir,
+              )
+            : ModuleGenerator.generateFlatModuleFile(
+                ~moduleName="API",
+                ~endpoints,
+                ~outputDir=config.outputDir,
+                ~overrideDir=?config.docOverrideDir,
+              ),
+        ])
+      : Pipeline.empty
+
+    let wrapperOutput = targets.rescriptWrapper
+      ? ThinWrapperGenerator.generateWrapper(~spec, ~endpoints, ~outputDir=config.outputDir, ~wrapperModuleName=CodegenUtils.toPascalCase(spec.info.title) ++ "Wrapper", ~generatedModulePrefix="")
+      : Pipeline.empty
+
+    let dtsOutput = targets.typescriptDts
+      ? TypeScriptDtsGenerator.generate(~spec, ~endpoints, ~outputDir=config.dtsOutputDir->Option.getOr(config.outputDir))
+      : Pipeline.empty
+
+    let tsWrapperOutput = targets.typescriptWrapper
+      ? TypeScriptWrapperGenerator.generate(~endpoints, ~outputDir=config.wrapperOutputDir->Option.getOr(config.outputDir), ~generatedModulePath="../generated")
+      : Pipeline.empty
+
+    Result.Ok(Pipeline.combine([baseOutput, wrapperOutput, dtsOutput, tsWrapperOutput]))
+  } catch {
+  | JsExn(err) => Result.Error(UnknownError({message: err->JsExn.message->Option.getOr("Unknown error"), context: None}))
+  | _ => Result.Error(UnknownError({message: "Unknown error", context: None}))
+  }
+}
+
+// Generate code from a single spec (with side effects)
+let generateSingleSpec = async (~spec: openAPISpec, ~config: generationConfig): generationResult => {
+  switch generateSingleSpecPure(~spec, ~config) {
+  | Result.Error(err) => Result.Error(err)
+  | Result.Ok(output) =>
+    switch FileSystem.writeFiles(output.files) {
+    | Result.Error(errors) => Result.Error(UnknownError({message: `Failed to write files: ${Array.join(errors, ", ")}`, context: None}))
+    | Result.Ok(filePaths) =>
+      let overrideFiles = switch config.generateDocOverrides {
+      | Some(true) =>
+          let allEndpoints = OpenAPIParser.getAllEndpoints(spec)
+          let endpoints = switch config.includeTags {
+          | None => allEndpoints
+          | Some(includeTags) => OpenAPIParser.filterByTags(~endpoints=allEndpoints, ~includeTags, ~excludeTags=config.excludeTags->Option.getOr([]))
+          }
+          let files = DocOverride.generateOverrideFiles(~spec, ~endpoints, ~outputDir=config.docOverrideDir->Option.getOr("./docs"), ~host=spec.info.title, ~groupByTag=config.modulePerTag, ())
+          FileSystem.writeFiles(files)->Result.getOr([])
+      | _ => []
+      }
+      Result.Ok({generatedFiles: Array.concat(filePaths, overrideFiles), diff: None, warnings: output.warnings})
+    }
+  }
+}
+
+// Process a single fork (pure - returns data)
+let processForkPure = (~baseSpec: openAPISpec, ~baseEndpoints: array<endpoint>, ~fork: forkSpec, ~config: generationConfig): result<Pipeline.t, codegenError> => {
+  try {
+    let forkEndpoints = OpenAPIParser.getAllEndpoints(fork.spec)
+    let diff = SpecDiffer.generateDiff(~baseSpec, ~forkSpec=fork.spec, ~baseEndpoints, ~forkEndpoints)
+    
+    let diffReportFile: option<FileSystem.fileToWrite> = config.generateDiffReport 
+      ? Some({path: FileSystem.makePath(config.outputDir, `${fork.name}-diff.md`), content: DiffReportGenerator.generateMarkdownReport(~diff, ~baseName="base", ~forkName=fork.name)})
+      : None
+
+    let (sharedSpec, extensionsSpec) = SpecMerger.mergeSpecs(~baseSpec, ~forkSpec=fork.spec, ~baseEndpoints, ~forkEndpoints, ~strategy=config.strategy)
+    let sharedEndpoints = OpenAPIParser.getAllEndpoints(sharedSpec)
+    let extensionEndpoints = OpenAPIParser.getAllEndpoints(extensionsSpec)
+    
+    let mergeReportFile: FileSystem.fileToWrite = {
+      path: FileSystem.makePath(config.outputDir, `${fork.name}-merge.md`),
+      content: DiffReportGenerator.generateMergeReport(~stats=SpecMerger.getMergeStats(~baseEndpoints, ~forkEndpoints, ~baseSchemas=baseSpec.components->Option.flatMap(c => c.schemas), ~forkSchemas=fork.spec.components->Option.flatMap(c => c.schemas)), ~baseName="base", ~forkName=fork.name)
+    }
+
+    let codeOutput = switch config.strategy {
+    | Separate =>
+      Pipeline.fromFile({
+        path: FileSystem.makePath(config.outputDir, `${fork.name}.res`),
+        content: ModuleGenerator.generateFlatModuleCode(
+          ~moduleName=CodegenUtils.toPascalCase(fork.name),
+          ~endpoints=forkEndpoints,
+          ~overrideDir=?config.docOverrideDir,
+        ),
+      })
+    | SharedBase =>
+        let baseName = config.baseInstanceName->Option.getOrThrow(~message="baseInstanceName required")
+        let basePrefix = config.baseModulePrefix->Option.getOr(CodegenUtils.toPascalCase(baseName))
+        ModuleGenerator.generateSeparatePerTagModules(~baseName, ~basePrefix, ~forkName=fork.name, ~sharedEndpoints, ~extensionEndpoints, ~sharedSchemas=sharedSpec.components->Option.flatMap(c => c.schemas), ~extensionSchemas=fork.spec.components->Option.flatMap(c => c.schemas), ~outputDir=config.outputDir, ~overrideDir=?config.docOverrideDir)
+    }
+
+    let targets = config.targets->Option.getOr({rescriptApi: true, rescriptWrapper: false, typescriptDts: false, typescriptWrapper: false})
+    let (wSpec, wShared, wExt, wBasePrefix) = switch config.strategy {
+    | Separate => (fork.spec, forkEndpoints, [], "")
+    | SharedBase => (sharedSpec, sharedEndpoints, extensionEndpoints, config.baseModulePrefix->Option.getOr(config.baseInstanceName->Option.map(CodegenUtils.toPascalCase)->Option.getOr("")))
+    }
+
+    let wrapperOutput = targets.rescriptWrapper 
+      ? ThinWrapperGenerator.generateWrapper(~spec=wSpec, ~endpoints=wShared, ~extensionEndpoints=wExt, ~outputDir=FileSystem.makePath(config.outputDir, fork.name), ~wrapperModuleName=CodegenUtils.toPascalCase(fork.name) ++ "Wrapper", ~generatedModulePrefix=CodegenUtils.toPascalCase(fork.name), ~baseModulePrefix=wBasePrefix)
+      : Pipeline.empty
+
+    let allWEndpoints = Array.concat(wShared, wExt)
+    let dtsOutput = targets.typescriptDts 
+      ? TypeScriptDtsGenerator.generate(~spec=wSpec, ~endpoints=allWEndpoints, ~outputDir=FileSystem.makePath(config.dtsOutputDir->Option.getOr(config.outputDir), fork.name))
+      : Pipeline.empty
+
+    let tsWrapperOutput = targets.typescriptWrapper 
+      ? TypeScriptWrapperGenerator.generate(~endpoints=allWEndpoints, ~outputDir=FileSystem.makePath(config.wrapperOutputDir->Option.getOr(config.outputDir), fork.name), ~generatedModulePath=`../../generated/${fork.name}`)
+      : Pipeline.empty
+
+    let reports = Pipeline.fromFiles([mergeReportFile, ...diffReportFile->Option.map(f => [f])->Option.getOr([])])
+    Result.Ok(Pipeline.combine([reports, codeOutput, wrapperOutput, dtsOutput, tsWrapperOutput]))
+  } catch {
+  | JsExn(err) => Result.Error(UnknownError({message: err->JsExn.message->Option.getOr("Unknown error"), context: None}))
+  | _ => Result.Error(UnknownError({message: "Unknown error", context: None}))
+  }
+}
+
+// Generate code from multiple specs (pure - returns data)
+let generateMultiSpecPure = (~baseSpec: openAPISpec, ~forkSpecs: array<forkSpec>, ~config: generationConfig): result<Pipeline.t, codegenError> => {
+  try {
+    let baseEndpoints = OpenAPIParser.getAllEndpoints(baseSpec)
+    let forkResults = forkSpecs->Array.map(fork => processForkPure(~baseSpec, ~baseEndpoints, ~fork, ~config))
+    
+    switch forkResults->Array.find(Result.isError) {
+    | Some(Result.Error(err)) => Result.Error(err)
+    | _ =>
+        let outputs = forkResults->Array.filterMap(res => switch res { | Ok(v) => Some(v) | Error(_) => None })
+        let targets = config.targets->Option.getOr(Config.defaultTargets())
+        let baseName = config.baseInstanceName->Option.getOrThrow(~message="baseInstanceName required")
+        let basePrefix = config.baseModulePrefix->Option.getOr(CodegenUtils.toPascalCase(baseName))
+        let baseOutputDir = FileSystem.makePath(config.outputDir, baseName)
+        
+        let baseWrappers = Pipeline.combine([
+          targets.rescriptWrapper ? ThinWrapperGenerator.generateWrapper(~spec=baseSpec, ~endpoints=baseEndpoints, ~outputDir=baseOutputDir, ~wrapperModuleName=basePrefix ++ "Wrapper", ~generatedModulePrefix=basePrefix) : Pipeline.empty,
+          targets.typescriptDts ? TypeScriptDtsGenerator.generate(~spec=baseSpec, ~endpoints=baseEndpoints, ~outputDir=FileSystem.makePath(config.dtsOutputDir->Option.getOr(config.outputDir), baseName)) : Pipeline.empty,
+          targets.typescriptWrapper ? TypeScriptWrapperGenerator.generate(~endpoints=baseEndpoints, ~outputDir=FileSystem.makePath(config.wrapperOutputDir->Option.getOr(config.outputDir), baseName), ~generatedModulePath=`../../generated/${baseName}`) : Pipeline.empty
+        ])
+        
+        Result.Ok(Pipeline.combine(Array.concat(outputs, [baseWrappers])))
+    }
+  } catch {
+  | JsExn(err) => Result.Error(UnknownError({message: err->JsExn.message->Option.getOr("Unknown error"), context: None}))
+  | _ => Result.Error(UnknownError({message: "Unknown error", context: None}))
+  }
+}
+
+// Generate code from multiple specs (with side effects)
+let generateMultiSpec = async (~baseSpec: openAPISpec, ~forkSpecs: array<forkSpec>, ~config: generationConfig): generationResult =>
+  switch generateMultiSpecPure(~baseSpec, ~forkSpecs, ~config) {
+  | Result.Error(err) => Result.Error(err)
+  | Result.Ok(output) =>
+      FileSystem.writeFiles(output.files)
+      ->Result.map(filePaths => ({generatedFiles: filePaths, diff: None, warnings: output.warnings}: generationSuccess))
+      ->Result.mapError(errors => UnknownError({message: `Failed to write files: ${Array.join(errors, ", ")}`, context: None}))
+  }
+
+// Compare two specs and generate diff report
+let compareSpecs = async (~baseSpec, ~forkSpec, ~baseName="base", ~forkName="fork", ~outputPath=?) => {
+  let diff = SpecDiffer.generateDiff(~baseSpec, ~forkSpec, ~baseEndpoints=OpenAPIParser.getAllEndpoints(baseSpec), ~forkEndpoints=OpenAPIParser.getAllEndpoints(forkSpec))
+  outputPath->Option.forEach(path => {
+    let _ = FileSystem.writeFile({path, content: DiffReportGenerator.generateMarkdownReport(~diff, ~baseName, ~forkName)})
+  })
+  diff
+}
+
+// Main generation function
+let generate = async (config: generationConfig): generationResult => {
+  switch await SchemaRefResolver.resolve(config.specPath) {
+  | Result.Error(message) => Result.Error(SpecResolutionError({url: config.specPath, message}))
+  | Result.Ok(baseSpec) =>
+      switch config.forkSpecs {
+      | None | Some([]) => await generateSingleSpec(~spec=baseSpec, ~config)
+      | Some(forkConfigs) =>
+          let forkResults = await forkConfigs
+            ->Array.map(async f => (await SchemaRefResolver.resolve(f.specPath))->Result.map(spec => ({name: f.name, spec}: forkSpec)))
+            ->promiseAll
+          
+          switch forkResults->Array.find(Result.isError) {
+          | Some(Result.Error(err)) => Result.Error(SpecResolutionError({url: "", message: err}))
+          | _ => await generateMultiSpec(~baseSpec, ~forkSpecs=forkResults->Array.filterMap(res => switch res { | Ok(v) => Some(v) | Error(_) => None }), ~config)
+          }
+      }
+  }
+}
+
+let createDefaultConfig = (url, outputDir): generationConfig => ({
+  specPath: url, outputDir, strategy: SharedBase, includeTags: None, excludeTags: None,
+  modulePerTag: true, generateDiffReport: true, breakingChangeHandling: Warn,
+  forkSpecs: None, generateDocOverrides: None, docOverrideDir: None,
+  targets: None, dtsOutputDir: None, wrapperOutputDir: None,
+  baseInstanceName: None, baseModulePrefix: None,
+})
+
+let generateFromUrl = async (~url, ~outputDir, ~config=?) => 
+  await generate({...config->Option.getOr(createDefaultConfig(url, outputDir)), specPath: url})
+
+let generateFromFile = async (~filePath, ~outputDir, ~config=?) => 
+  await generate({...config->Option.getOr(createDefaultConfig(filePath, outputDir)), specPath: filePath})

package/src/Types.res

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// Types.res - Core OpenAPI and generation types (refactored & compact)
+
+// ============= JSON Schema Types =============
+type rec jsonSchemaType =
+  | String
+  | Number
+  | Integer
+  | Boolean
+  | Array(jsonSchemaType)
+  | Object
+  | Null
+  | Unknown
+
+and jsonSchema = {
+  @as("type") type_: option<jsonSchemaType>,
+  properties: option<dict<jsonSchema>>,
+  items: option<jsonSchema>,
+  required: option<array<string>>,
+  enum: option<array<JSON.t>>,
+  @as("$ref") ref: option<string>,
+  allOf: option<array<jsonSchema>>,
+  oneOf: option<array<jsonSchema>>,
+  anyOf: option<array<jsonSchema>>,
+  description: option<string>,
+  format: option<string>,
+  minLength: option<int>,
+  maxLength: option<int>,
+  minimum: option<float>,
+  maximum: option<float>,
+  pattern: option<string>,
+  nullable: option<bool>,
+}
+
+// ============= OpenAPI 3.1 Types =============
+type httpMethod = [#GET | #POST | #PUT | #PATCH | #DELETE | #HEAD | #OPTIONS]
+
+type mediaType = {
+  schema: option<jsonSchema>,
+  example: option<JSON.t>,
+  examples: option<dict<JSON.t>>,
+}
+
+type requestBody = {
+  description: option<string>,
+  content: dict<mediaType>,
+  required: option<bool>,
+}
+
+type response = {
+  description: string,
+  content: option<dict<mediaType>>,
+}
+
+type parameter = {
+  name: string,
+  @as("in") in_: string,
+  description: option<string>,
+  required: option<bool>,
+  schema: option<jsonSchema>,
+}
+
+type operation = {
+  operationId: option<string>,
+  summary: option<string>,
+  description: option<string>,
+  tags: option<array<string>>,
+  requestBody: option<requestBody>,
+  responses: dict<response>,
+  parameters: option<array<parameter>>,
+}
+
+type endpoint = {
+  path: string,
+  method: string,
+  operationId: option<string>,
+  summary: option<string>,
+  description: option<string>,
+  tags: option<array<string>>,
+  requestBody: option<requestBody>,
+  responses: dict<response>,
+  parameters: option<array<parameter>>,
+}
+
+type pathItem = {
+  get: option<operation>,
+  post: option<operation>,
+  put: option<operation>,
+  patch: option<operation>,
+  delete: option<operation>,
+  head: option<operation>,
+  options: option<operation>,
+  parameters: option<array<parameter>>,
+}
+
+type components = {schemas: option<dict<jsonSchema>>}
+
+type info = {
+  title: string,
+  version: string,
+  description: option<string>,
+}
+
+type openAPISpec = {
+  openapi: string,
+  info: info,
+  paths: dict<pathItem>,
+  components: option<components>,
+}
+
+// ============= Re-exports from focused modules =============
+// Config types
+type generationStrategy = Config.generationStrategy =
+  | Separate
+  | SharedBase
+
+type breakingChangeHandling = Config.breakingChangeHandling = | Error | Warn | Ignore
+type forkSpecConfig = Config.forkSpecConfig = {name: string, specPath: string}
+type generationTargets = Config.generationTargets = {
+  rescriptApi: bool,
+  rescriptWrapper: bool,
+  typescriptDts: bool,
+  typescriptWrapper: bool,
+}
+type generationConfig = Config.t
+
+type forkSpec = {
+  name: string,
+  spec: openAPISpec,
+}
+
+// Error types - use `=` syntax to re-export constructors
+type errorContext = CodegenError.context = {
+  path: string,
+  operation: string,
+  schema: option<JSON.t>,
+}
+
+type codegenError = CodegenError.t =
+  | SpecResolutionError({url: string, message: string})
+  | SchemaParseError({context: errorContext, reason: string})
+  | ReferenceError({ref: string, context: errorContext})
+  | ValidationError({schema: string, input: JSON.t, issues: array<string>})
+  | CircularSchemaError({ref: string, depth: int, path: string})
+  | FileWriteError({filePath: string, message: string})
+  | InvalidConfigError({field: string, message: string})
+  | UnknownError({message: string, context: option<errorContext>})
+
+type warning = CodegenError.Warning.t =
+  | FallbackToJson({reason: string, context: errorContext})
+  | UnsupportedFeature({feature: string, fallback: string, location: string})
+  | DepthLimitReached({depth: int, path: string})
+  | MissingSchema({ref: string, location: string})
+  | IntersectionNotFullySupported({location: string, note: string})
+  | ComplexUnionSimplified({location: string, types: string})
+
+// ============= Diff Types =============
+type endpointDiff = {
+  path: string,
+  method: string,
+  requestBodyChanged: bool,
+  responseChanged: bool,
+  breakingChange: bool,
+}
+
+type schemaDiff = {
+  name: string,
+  breakingChange: bool,
+}
+
+type specDiff = {
+  addedEndpoints: array<endpoint>,
+  removedEndpoints: array<endpoint>,
+  modifiedEndpoints: array<endpointDiff>,
+  addedSchemas: array<string>,
+  removedSchemas: array<string>,
+  modifiedSchemas: array<schemaDiff>,
+}
+
+// ============= Generation Result Types =============
+type generationSuccess = {
+  generatedFiles: array<string>,
+  diff: option<specDiff>,
+  warnings: array<warning>,
+}
+
+type generationResult = result<generationSuccess, codegenError>
+
+// ============= Re-export helper modules =============
+module CodegenError = CodegenError
+
+module Warning = {
+  include CodegenError.Warning
+}

package/src/core/CodegenUtils.res

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// CodegenUtils.res - Utility functions for code generation
+
+// Convert a string to PascalCase
+@module("@std/text") external toPascalCase: string => string = "toPascalCase"
+
+// Convert a string to camelCase
+@module("@std/text") external toCamelCase: string => string = "toCamelCase"
+
+// Sanitize identifier (remove special characters, ensure valid ReScript identifier)
+let sanitizeIdentifier = (str: string): string =>
+  str
+  ->String.replaceAll("{", "")->String.replaceAll("}", "")
+  ->String.replaceAll("[", "")->String.replaceAll("]", "")
+  ->String.replaceAll(".", "_")->String.replaceAll("-", "_")
+  ->String.replaceAll("/", "_")->String.replaceAll(" ", "_")
+
+// Generate type name from path and method
+let generateTypeName = (~prefix="", path: string, suffix: string): string => {
+  let cleaned = path
+    ->String.replaceAll("/", "_")
+    ->sanitizeIdentifier
+    ->String.split("_")
+    ->Array.filter(part => part != "")
+    ->Array.map(toPascalCase)
+    ->Array.join("")
+  
+  prefix ++ cleaned ++ suffix
+}
+
+// Generate operation name from operationId or path + method
+let generateOperationName = (operationId: option<string>, path: string, method: string): string =>
+  switch operationId {
+  | Some(id) => toCamelCase(sanitizeIdentifier(id))
+  | None =>
+      method->String.toLowerCase ++ path
+        ->String.split("/")
+        ->Array.filter(part => part != "" && !(part->String.startsWith("{")))
+        ->Array.map(toCamelCase)
+        ->Array.join("")
+  }
+
+// Escape ReScript string
+let escapeString = (str: string): string =>
+  str
+  ->String.replaceAll("\\", "\\\\")->String.replaceAll("\"", "\\\"")
+  ->String.replaceAll("\n", "\\n")->String.replaceAll("\r", "\\r")
+  ->String.replaceAll("\t", "\\t")
+
+// Generate file header
+let generateFileHeader = (~description: string): string =>
+  `// ${description}
+// Generated by @f3liz/rescript-autogen-openapi
+// DO NOT EDIT - This file is auto-generated
+
+`
+
+// Indent code
+let indent = (code: string, level: int): string => {
+  let spaces = "  "->String.repeat(level)
+  code
+  ->String.split("\n")
+  ->Array.map(line => line->String.trim == "" ? "" : spaces ++ line)
+  ->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",
+  "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"
+]
+
+// Escape ReScript keywords by adding underscore suffix
+let escapeKeyword = (name: string): string => rescriptKeywords->Array.includes(name) ? name ++ "_" : name
+
+// 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`
+  }
+
+// Generate DocString comment (multi-line /** ... */ format) from markdown
+let generateDocString = (~summary=?, ~description=?, ()): string => {
+  let content = switch (summary, description) {
+  | (None, None) => None
+  | (Some(s), None) => Some(s)
+  | (None, Some(d)) => Some(d)
+  | (Some(s), Some(d)) => Some(s == d ? s : s ++ "\n\n" ++ d)
+  }
+  
+  content->Option.map(text => {
+    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"
+    }
+  })->Option.getOr("")
+}
+
+// Shared type signature for the fetch function used in generated code
+let fetchTypeSignature = "(~url: string, ~method_: string, ~body: option<JSON.t>) => Promise.t<JSON.t>"