@f3liz/rescript-autogen-openapi 0.3.1

package/src/generators/ComponentSchemaGenerator.res

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// ComponentSchemaGenerator.res - Generate shared component schema module
+open Types
+
+let rec extractReferencedSchemaNames = (irType: SchemaIR.irType) =>
+  switch irType {
+  | Reference(ref) =>
+    // After normalization, ref is just the schema name (no path prefix)
+    [ref]
+  | Array({items}) => extractReferencedSchemaNames(items)
+  | Object({properties}) => properties->Array.flatMap(((_name, fieldType, _)) => extractReferencedSchemaNames(fieldType))
+  | Union(types)
+  | Intersection(types) =>
+    types->Array.flatMap(extractReferencedSchemaNames)
+  | Option(inner) => extractReferencedSchemaNames(inner)
+  | _ => []
+  }
+
+let generate = (~spec, ~outputDir) => {
+  let (context, parseWarnings) =
+    spec.components
+    ->Option.flatMap(components => components.schemas)
+    ->Option.mapOr(({SchemaIR.schemas: Dict.make()}, []), schemas =>
+      SchemaIRParser.parseComponentSchemas(schemas)
+    )
+
+  if Dict.size(context.schemas) == 0 {
+    Pipeline.empty
+  } else {
+    let schemas = Dict.valuesToArray(context.schemas)
+    let schemaNameMap = Dict.fromArray(schemas->Array.map(s => (s.name, s)))
+
+    // Build dependency edges for topological sort
+    // Edge (A, B) means "A depends on B" so B must come before A
+    let allNodes = schemas->Array.map(s => s.name)
+    let edges = schemas->Array.flatMap(schema => {
+      let references =
+        extractReferencedSchemaNames(schema.type_)->Array.filter(name =>
+          Dict.has(schemaNameMap, name) && name != schema.name
+        )
+      references->Array.map(dep => (schema.name, dep))
+    })
+
+    // Use toposort with cycle tolerance: if there's a cycle, catch and fall back
+    // Note: toposort returns dependents first, dependencies last.
+    // We reverse to get execution order (dependencies first).
+    let sortedNames = try {
+      Toposort.sortArray(allNodes, edges)->Array.toReversed
+    } catch {
+    | _ =>
+      // Cycles exist — remove back-edges and re-sort
+      let visited = Dict.make()
+      let inStack = Dict.make()
+      let cycleEdges: array<(string, string)> = []
+      
+      let rec dfs = (node) => {
+        if Dict.get(inStack, node)->Option.getOr(false) {
+          ()
+        } else if Dict.get(visited, node)->Option.getOr(false) {
+          ()
+        } else {
+          Dict.set(visited, node, true)
+          Dict.set(inStack, node, true)
+          edges->Array.forEach(((from, to)) => {
+            if from == node {
+              if Dict.get(inStack, to)->Option.getOr(false) {
+                cycleEdges->Array.push((from, to))
+              } else {
+                dfs(to)
+              }
+            }
+          })
+          Dict.set(inStack, node, false)
+        }
+      }
+      allNodes->Array.forEach(dfs)
+      
+      let nonCycleEdges = edges->Array.filter(((from, to)) =>
+        !(cycleEdges->Array.some(((cf, ct)) => cf == from && ct == to))
+      )
+      try {
+        Toposort.sortArray(allNodes, nonCycleEdges)->Array.toReversed
+      } catch {
+      | _ => allNodes->Array.toSorted((a, b) => String.compare(a, b))
+      }
+    }
+
+    let finalSortedSchemas = sortedNames->Array.filterMap(name => Dict.get(schemaNameMap, name))
+    let availableSchemaNames = finalSortedSchemas->Array.map(s => s.name)
+    let warnings = Array.copy(parseWarnings)
+
+    // Detect self-referencing schemas (schema references itself directly or indirectly through properties)
+    let selfRefSchemas = Dict.make()
+    finalSortedSchemas->Array.forEach(schema => {
+      let refs = extractReferencedSchemaNames(schema.type_)
+      if refs->Array.some(name => name == schema.name) {
+        Dict.set(selfRefSchemas, schema.name, true)
+      }
+    })
+
+    let moduleCodes = finalSortedSchemas->Array.map(schema => {
+      let isSelfRef = Dict.get(selfRefSchemas, schema.name)->Option.getOr(false)
+      let selfRefName = isSelfRef ? Some(schema.name) : None
+      
+      let typeCtx = GenerationContext.make(
+        ~path=`ComponentSchemas.${schema.name}`,
+        ~insideComponentSchemas=true,
+        ~availableSchemas=availableSchemaNames,
+        ~selfRefName?,
+        (),
+      )
+
+      let typeCode = IRToTypeGenerator.generateTypeWithContext(~ctx=typeCtx, ~depth=0, schema.type_)
+
+      // Iteratively resolve nested extractions using typeCtx
+      let processed = ref(0)
+      while processed.contents < Array.length(typeCtx.extractedTypes) {
+        let idx = processed.contents
+        let {irType, isUnboxed, _}: GenerationContext.extractedType = typeCtx.extractedTypes->Array.getUnsafe(idx)
+        if !isUnboxed {
+          ignore(IRToTypeGenerator.generateTypeWithContext(~ctx=typeCtx, ~depth=0, ~inline=false, irType))
+        } else {
+          switch irType {
+          | Union(types) =>
+            types->Array.forEach(memberType => {
+              ignore(IRToTypeGenerator.generateTypeWithContext(~ctx=typeCtx, ~depth=0, ~inline=true, memberType))
+            })
+          | _ => ignore(IRToTypeGenerator.generateTypeWithContext(~ctx=typeCtx, ~depth=0, ~inline=false, irType))
+          }
+        }
+        processed := idx + 1
+      }
+
+      let allExtracted = Array.copy(typeCtx.extractedTypes)->Array.toReversed
+      let extractedTypeMap = if Array.length(allExtracted) > 0 { Some(allExtracted) } else { None }
+
+      // Generate schema with extracted type map for correct references
+      let schemaCtx = GenerationContext.make(
+        ~path=`ComponentSchemas.${schema.name}`,
+        ~insideComponentSchemas=true,
+        ~availableSchemas=availableSchemaNames,
+        ~selfRefName?,
+        (),
+      )
+      let schemaCode = IRToSuryGenerator.generateSchemaWithContext(~ctx=schemaCtx, ~depth=0, ~extractedTypeMap?, schema.type_)
+
+      warnings->Array.pushMany(typeCtx.warnings)
+      warnings->Array.pushMany(schemaCtx.warnings)
+
+      // Generate extracted auxiliary types and schemas (use ctx for dedup)
+      let extractedTypeDefs = allExtracted->Array.map(({typeName, irType, isUnboxed}: GenerationContext.extractedType) => {
+        let auxTypeCode = if isUnboxed {
+          switch irType {
+          | Union(types) =>
+            let body = IRToTypeGenerator.generateUnboxedVariantBody(~ctx=typeCtx, types)
+            `@unboxed type ${typeName} = ${body}`
+          | _ =>
+            let auxType = IRToTypeGenerator.generateTypeWithContext(~ctx=typeCtx, ~depth=0, irType)
+            `type ${typeName} = ${auxType}`
+          }
+        } else {
+          let auxType = IRToTypeGenerator.generateTypeWithContext(~ctx=typeCtx, ~depth=0, irType)
+          `type ${typeName} = ${auxType}`
+        }
+        let auxSchemaCtx = GenerationContext.make(
+          ~path=`ComponentSchemas.${schema.name}.${typeName}`,
+          ~insideComponentSchemas=true,
+          ~availableSchemas=availableSchemaNames,
+          (),
+        )
+        // Exclude the current type from the map to avoid self-reference
+        let filteredMap = allExtracted->Array.filter(({typeName: tn}: GenerationContext.extractedType) => tn != typeName)
+        let auxExtractedTypeMap = if Array.length(filteredMap) > 0 { Some(filteredMap) } else { None }
+        let auxSchema = IRToSuryGenerator.generateSchemaWithContext(~ctx=auxSchemaCtx, ~depth=0, ~extractedTypeMap=?auxExtractedTypeMap, irType)
+        `  ${auxTypeCode}\n  let ${typeName}Schema = ${auxSchema}`
+      })
+
+      let docComment = schema.description->Option.mapOr("", d =>
+        CodegenUtils.generateDocString(~description=d, ())
+      )
+
+      let extractedBlock = if Array.length(extractedTypeDefs) > 0 {
+        extractedTypeDefs->Array.join("\n") ++ "\n"
+      } else {
+        ""
+      }
+
+      // Use `type rec t` for self-referential types
+      let typeKeyword = isSelfRef ? "type rec t" : "type t"
+      // Wrap schema in S.recursive for self-referential types
+      let finalSchemaCode = isSelfRef
+        ? `S.recursive("${schema.name}", schema => ${schemaCode})`
+        : schemaCode
+
+      `${docComment}module ${CodegenUtils.toPascalCase(schema.name)} = {
+${extractedBlock}  ${typeKeyword} = ${typeCode}
+  let schema = ${finalSchemaCode}
+}`
+    })
+
+    let fileHeader = CodegenUtils.generateFileHeader(~description="Shared component schemas")
+    let fileContent = `${fileHeader}\n\n${moduleCodes->Array.join("\n\n")}`
+
+    Pipeline.fromFilesAndWarnings(
+      [{path: FileSystem.makePath(outputDir, "ComponentSchemas.res"), content: fileContent}],
+      warnings,
+    )
+  }
+}

package/src/generators/DiffReportGenerator.res

@@ -0,0 +1,152 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// DiffReportGenerator.res - Generate Markdown reports for API diffs and merges
+open Types
+
+let formatEndpointName = (endpoint: endpoint) => {
+  let methodPart = endpoint.method->String.toUpperCase
+  let operationIdPart = endpoint.operationId->Option.mapOr("", id => ` (${id})`)
+  `${methodPart} ${endpoint.path}${operationIdPart}`
+}
+
+let formatTags = tags =>
+  tags->Option.mapOr("", tagList =>
+    tagList->Array.length == 0 ? "" : ` [${tagList->Array.join(", ")}]`
+  )
+
+let generateMarkdownReport = (~diff: specDiff, ~baseName, ~forkName) => {
+  let generateSection = (title, items, formatter) =>
+    items->Array.length == 0 ? "" : `\n### ${title}\n\n${items->Array.map(formatter)->Array.join("\n")}\n`
+
+  let totalChanges = SpecDiffer.countChanges(diff)
+  let breakingChangesText = SpecDiffer.hasBreakingChanges(diff) ? "⚠️ Yes" : "✓ No"
+
+  let summaryLines = [
+    `- **Total Changes**: ${totalChanges->Int.toString}`,
+    `- **Added Endpoints**: ${diff.addedEndpoints->Array.length->Int.toString}`,
+    `- **Removed Endpoints**: ${diff.removedEndpoints->Array.length->Int.toString}`,
+    `- **Modified Endpoints**: ${diff.modifiedEndpoints->Array.length->Int.toString}`,
+    `- **Added Schemas**: ${diff.addedSchemas->Array.length->Int.toString}`,
+    `- **Removed Schemas**: ${diff.removedSchemas->Array.length->Int.toString}`,
+    `- **Modified Schemas**: ${diff.modifiedSchemas->Array.length->Int.toString}`,
+    `- **Breaking Changes**: ${breakingChangesText}`,
+  ]->Array.join("\n")
+
+  let reportParts = [
+    `# API Diff Report: ${baseName} → ${forkName}\n\n## Summary\n\n${summaryLines}`,
+    generateSection("Added Endpoints", diff.addedEndpoints, (endpoint: endpoint) => {
+      let endpointName = formatEndpointName(endpoint)
+      let tags = formatTags(endpoint.tags)
+      let summary = endpoint.summary->Option.mapOr("", summary => `\n  ${summary}`)
+      `- **${endpointName}**${tags}${summary}`
+    }),
+    generateSection("Removed Endpoints", diff.removedEndpoints, (endpoint: endpoint) => {
+      let endpointName = formatEndpointName(endpoint)
+      let tags = formatTags(endpoint.tags)
+      `- **${endpointName}**${tags}`
+    }),
+    generateSection("Modified Endpoints", diff.modifiedEndpoints, (endpointDiff: endpointDiff) => {
+      let methodPart = endpointDiff.method->String.toUpperCase
+      let breakingText = endpointDiff.breakingChange ? " **⚠️ BREAKING**" : ""
+      let changes =
+        [endpointDiff.requestBodyChanged ? "body" : "", endpointDiff.responseChanged ? "response" : ""]
+        ->Array.filter(x => x != "")
+        ->Array.join(", ")
+      `- **${methodPart} ${endpointDiff.path}**${breakingText}: Changed ${changes}`
+    }),
+    generateSection("Added Schemas", diff.addedSchemas, schemaName => `- \`${schemaName}\``),
+    generateSection("Removed Schemas", diff.removedSchemas, schemaName => `- \`${schemaName}\``),
+    generateSection("Modified Schemas", diff.modifiedSchemas, (schemaDiff: schemaDiff) => {
+      let breakingText = schemaDiff.breakingChange ? " **⚠️ BREAKING**" : ""
+      `- \`${schemaDiff.name}\`${breakingText}`
+    }),
+    `\n---\n*Generated on ${Date.make()->Date.toISOString}*`,
+  ]
+
+  reportParts->Array.filter(part => part != "")->Array.join("\n")
+}
+
+let generateCompactSummary = (diff: specDiff) => {
+  let totalChanges = SpecDiffer.countChanges(diff)
+  let addedCount = diff.addedEndpoints->Array.length
+  let removedCount = diff.removedEndpoints->Array.length
+  let modifiedCount = diff.modifiedEndpoints->Array.length
+  let breakingText = SpecDiffer.hasBreakingChanges(diff) ? " (BREAKING)" : ""
+
+  `Found ${totalChanges->Int.toString} changes: +${addedCount->Int.toString} -${removedCount->Int.toString} ~${modifiedCount->Int.toString} endpoints${breakingText}`
+}
+
+let generateMergeReport = (~stats: SpecMerger.mergeStats, ~baseName, ~forkName) => {
+  let sharedEndpoints = stats.sharedEndpointCount->Int.toString
+  let sharedSchemas = stats.sharedSchemaCount->Int.toString
+  let extensionEndpoints = stats.forkExtensionCount->Int.toString
+  let extensionSchemas = stats.forkSchemaCount->Int.toString
+
+  `
+    |# 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 ${Date.make()->Date.toISOString}*
+    |`->CodegenUtils.trimMargin
+}
+
+let generateEndpointsByTagReport = (endpoints: array<endpoint>) => {
+  let endpointsByTag = Dict.make()
+  let untaggedEndpoints = []
+
+  endpoints->Array.forEach(endpoint =>
+    switch endpoint.tags {
+    | None
+    | Some([]) =>
+      untaggedEndpoints->Array.push(endpoint)
+    | Some(tags) =>
+      tags->Array.forEach(tag => {
+        let existing = Dict.get(endpointsByTag, tag)->Option.getOr([])
+        existing->Array.push(endpoint)
+        Dict.set(endpointsByTag, tag, existing)
+      })
+    }
+  )
+
+  let tagSections =
+    Dict.keysToArray(endpointsByTag)
+    ->Array.toSorted(String.compare)
+    ->Array.map(tag => {
+      let tagEndpoints = Dict.get(endpointsByTag, tag)->Option.getOr([])
+      let count = tagEndpoints->Array.length->Int.toString
+      let endpointList =
+        tagEndpoints->Array.map(endpoint => `- ${formatEndpointName(endpoint)}`)->Array.join("\n")
+      `### ${tag} (${count})\n\n${endpointList}`
+    })
+    ->Array.join("\n\n")
+
+  let untaggedSection =
+    untaggedEndpoints->Array.length > 0
+      ? {
+          let count = untaggedEndpoints->Array.length->Int.toString
+          let endpointList =
+            untaggedEndpoints
+            ->Array.map(endpoint => `- ${formatEndpointName(endpoint)}`)
+            ->Array.join("\n")
+          `\n\n### Untagged (${count})\n\n${endpointList}`
+        }
+      : ""
+
+  `## Endpoints by Tag\n\n${tagSections}${untaggedSection}`
+}

package/src/generators/EndpointGenerator.res

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// EndpointGenerator.res - Generate API endpoint functions
+open Types
+
+let getJsonSchemaFromRequestBody = (requestBody: option<requestBody>) =>
+  requestBody->Option.flatMap(body =>
+    Dict.toArray(body.content)->Array.get(0)->Option.flatMap(((_contentType, mediaType)) => mediaType.schema)
+  )
+
+let generateTypeCodeAndSchemaCode = (~jsonSchema, ~typeName, ~schemaName, ~modulePrefix="") => {
+  let (ir, _) = SchemaIRParser.parseJsonSchema(jsonSchema)
+  let (typeCode, _, extractedTypes) = IRToTypeGenerator.generateNamedType(
+    ~namedSchema={name: typeName, description: jsonSchema.description, type_: ir},
+    ~modulePrefix,
+  )
+  let (schemaCode, _) = IRToSuryGenerator.generateNamedSchema(
+    ~namedSchema={name: schemaName, description: jsonSchema.description, type_: ir},
+    ~modulePrefix,
+    ~extractedTypes,
+  )
+  (typeCode, schemaCode)
+}
+
+let generateEndpointFunction = (endpoint: endpoint, ~overrideDir=?, ~moduleName=?) => {
+  let functionName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method)
+  let requestTypeName = `${functionName}Request`
+  let hasRequestBody = endpoint.requestBody->Option.isSome
+  let requestBody = endpoint.requestBody->Option.getOr({
+    content: Dict.make(),
+    description: None,
+    required: Some(false),
+  })
+  let isRequestBodyRequired = requestBody.required->Option.getOr(false)
+  
+  let bodyParam = hasRequestBody
+    ? (isRequestBodyRequired ? `~body: ${requestTypeName}` : `~body: option<${requestTypeName}>=?`)
+    : ""
+  
+  // Clean up function signature: handle comma between body and fetch params
+  let paramSep = hasRequestBody ? ", " : ""
+  
+  let bodyValueConversion = hasRequestBody
+    ? (
+        isRequestBodyRequired
+          ? `  let jsonBody = body->S.reverseConvertToJsonOrThrow(${functionName}RequestSchema)`
+          : `  let jsonBody = body->Option.map(b => b->S.reverseConvertToJsonOrThrow(${functionName}RequestSchema))`
+      )
+    : ""
+  
+  let successResponse = ["200", "201", "202", "204"]
+    ->Array.filterMap(code => Dict.get(endpoint.responses, code))
+    ->Array.get(0)
+    
+  let responseHandling = successResponse->Option.mapOr("  response", response =>
+    response.content->Option.mapOr("  let _ = response\n  ()", content =>
+      Dict.toArray(content)->Array.length > 0
+        ? `  let value = response->S.parseOrThrow(${functionName}ResponseSchema)\n  value`
+        : "  response"
+    )
+  )
+
+  let description = switch (overrideDir, moduleName) {
+  | (Some(dir), Some(mName)) =>
+    DocOverride.readOverrideWithValidation(
+      dir,
+      mName,
+      functionName,
+      DocOverride.generateEndpointHash(endpoint),
+    )->(
+      overrideResult =>
+        switch overrideResult {
+        | DocOverride.ValidOverride(v)
+        | DocOverride.InvalidHash({override: v}) =>
+          Some(v)
+        | _ => endpoint.description
+        }
+    )
+  | _ => endpoint.description
+  }
+  
+  let docComment = CodegenUtils.generateDocString(
+    ~summary=?endpoint.summary,
+    ~description=?description,
+    (),
+  )
+  
+  let code = `
+    |${docComment->String.trimEnd}
+    |let ${functionName} = (${bodyParam}${paramSep}~fetch: ${CodegenUtils.fetchTypeSignature}): promise<${functionName}Response> => {
+    |${bodyValueConversion}
+    |  fetch(
+    |    ~url="${endpoint.path}",
+    |    ~method_="${endpoint.method->String.toUpperCase}",
+    |    ~body=${hasRequestBody ? "Some(jsonBody)" : "None"},
+    |  )->Promise.then(response => {
+    |${responseHandling}
+    |    ->Promise.resolve
+    |  })
+    |}`
+  
+  code->CodegenUtils.trimMargin
+}
+
+let generateEndpointCode = (endpoint, ~overrideDir=?, ~moduleName=?, ~modulePrefix="") => {
+  let functionName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method)
+  
+  let requestJsonSchema = getJsonSchemaFromRequestBody(endpoint.requestBody)
+  
+  let responseJsonSchema = ["200", "201", "202", "204"]
+    ->Array.filterMap(code => Dict.get(endpoint.responses, code))
+    ->Array.get(0)
+    ->Option.flatMap(resp => resp.content)
+    ->Option.flatMap(content =>
+      Dict.toArray(content)->Array.get(0)->Option.flatMap(((_contentType, mediaType)) => mediaType.schema)
+    )
+  
+  let requestPart = requestJsonSchema->Option.mapOr("", schema => {
+    let (typeCode, schemaCode) = generateTypeCodeAndSchemaCode(
+      ~jsonSchema=schema,
+      ~typeName=`${functionName}Request`,
+      ~schemaName=`${functionName}Request`,
+      ~modulePrefix,
+    )
+    `${typeCode}\n\n${schemaCode}`
+  })
+  
+  let responsePart = responseJsonSchema->Option.mapOr(`type ${functionName}Response = unit`, schema => {
+    let (typeCode, schemaCode) = generateTypeCodeAndSchemaCode(
+      ~jsonSchema=schema,
+      ~typeName=`${functionName}Response`,
+      ~schemaName=`${functionName}Response`,
+      ~modulePrefix,
+    )
+    `${typeCode}\n\n${schemaCode}`
+  })
+  
+  [requestPart, responsePart, generateEndpointFunction(endpoint, ~overrideDir?, ~moduleName?)]
+  ->Array.filter(s => s != "")
+  ->Array.join("\n\n")
+}
+
+let generateEndpointModule = (~endpoint, ~modulePrefix="") => {
+  let functionName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method)
+  let header = CodegenUtils.generateFileHeader(~description=endpoint.summary->Option.getOr(`API: ${endpoint.path}`))
+  `
+    |${header->String.trimEnd}
+    |
+    |module ${CodegenUtils.toPascalCase(functionName)} = {
+    |${generateEndpointCode(endpoint, ~modulePrefix)->CodegenUtils.indent(2)}
+    |}
+    |`->CodegenUtils.trimMargin
+}
+
+let generateEndpointsModule = (~moduleName, ~endpoints, ~description=?, ~overrideDir=?, ~modulePrefix="") => {
+  let header = CodegenUtils.generateFileHeader(~description=description->Option.getOr(`API for ${moduleName}`))
+  let body =
+    endpoints
+    ->Array.map(ep => generateEndpointCode(ep, ~overrideDir?, ~moduleName, ~modulePrefix)->CodegenUtils.indent(2))
+    ->Array.join("\n\n")
+
+  `
+    |${header->String.trimEnd}
+    |
+    |module ${moduleName} = {
+    |${body}
+    |}
+    |`->CodegenUtils.trimMargin
+}
+
+let generateEndpointSignature = (endpoint) => {
+  let functionName = CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method)
+  let summaryPrefix = endpoint.summary->Option.mapOr("", s => `// ${s}\n`)
+  let bodyParam = endpoint.requestBody->Option.isSome ? "~body: 'body, " : ""
+  `${summaryPrefix}let ${functionName}: (${bodyParam}~fetch: fetchFn) => promise<${functionName}Response>`
+}