@f3liz/rescript-autogen-openapi 0.1.0

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,172 @@
+// 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, _) = IRToTypeGenerator.generateNamedType(
+    ~namedSchema={name: typeName, description: jsonSchema.description, type_: ir},
+    ~modulePrefix,
+  )
+  let (schemaCode, _) = IRToSuryGenerator.generateNamedSchema(
+    ~namedSchema={name: schemaName, description: jsonSchema.description, type_: ir},
+    ~modulePrefix,
+  )
+  (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}>=?`)
+    : "~body as _"
+  
+  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}, ~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>`
+}

package/src/generators/IRToSuryGenerator.res

@@ -0,0 +1,199 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// IRToSuryGenerator.res - Generate Sury schema code from Schema IR
+open Types
+
+let addWarning = GenerationContext.addWarning
+
+let applyConstraints = (base, min, max, toString) => {
+  let s1 = switch min {
+  | Some(v) => `${base}->S.min(${toString(v)})`
+  | None => base
+  }
+  switch max {
+  | Some(v) => `${s1}->S.max(${toString(v)})`
+  | None => s1
+  }
+}
+
+let rec generateSchemaWithContext = (~ctx: GenerationContext.t, ~depth=0, irType: SchemaIR.irType): string => {
+  // We keep a high depth limit just to prevent infinite recursion on circular schemas that escaped IRBuilder
+  if depth > 100 {
+    addWarning(ctx, DepthLimitReached({depth, path: ctx.path}))
+    "S.json"
+  } else {
+    let recurse = nextIrType => generateSchemaWithContext(~ctx, ~depth=depth + 1, nextIrType)
+
+    switch irType {
+    | String({constraints: c}) =>
+      let s = applyConstraints("S.string", c.minLength, c.maxLength, v => Int.toString(v))
+      switch c.pattern {
+      | Some(p) => `${s}->S.pattern(%re("/${CodegenUtils.escapeString(p)}/"))`
+      | None => s
+      }
+    | Number({constraints: c}) =>
+      applyConstraints("S.float", c.minimum, c.maximum, v => Float.toInt(v)->Int.toString)
+    | Integer({constraints: c}) =>
+      applyConstraints("S.int", c.minimum, c.maximum, v => Float.toInt(v)->Int.toString)
+    | Boolean => "S.bool"
+    | Null => "S.null"
+    | Array({items, constraints: c}) =>
+      applyConstraints(`S.array(${recurse(items)})`, c.minItems, c.maxItems, v => Int.toString(v))
+    | Object({properties, additionalProperties}) =>
+      if Array.length(properties) == 0 {
+        switch additionalProperties {
+        | Some(valueType) => `S.dict(${recurse(valueType)})`
+        | None => "S.json"
+        }
+      } else {
+        let fields =
+          properties
+          ->Array.map(((name, fieldType, isRequired)) => {
+            let schemaCode = recurse(fieldType)
+            let camelName = name->CodegenUtils.toCamelCase->CodegenUtils.escapeKeyword
+            isRequired
+              ? `    ${camelName}: s.field("${name}", ${schemaCode}),`
+              : `    ${camelName}: s.fieldOr("${name}", S.nullableAsOption(${schemaCode}), None),`
+          })
+          ->Array.join("\n")
+        `S.object(s => {\n${fields}\n  })`
+      }
+    | Literal(value) =>
+      switch value {
+      | StringLiteral(s) => `S.literal("${CodegenUtils.escapeString(s)}")`
+      | NumberLiteral(n) => `S.literal(${Float.toString(n)})`
+      | BooleanLiteral(b) => `S.literal(${b ? "true" : "false"})`
+      | NullLiteral => "S.literal(null)"
+      }
+    | Union(types) =>
+      let (hasArray, hasNonArray, arrayItemType, nonArrayType) = types->Array.reduce(
+        (false, false, None, None),
+        ((hArr, hNonArr, arrItem, nonArr), t) =>
+          switch t {
+          | Array({items}) => (true, hNonArr, Some(items), nonArr)
+          | _ => (hArr, true, arrItem, Some(t))
+          },
+      )
+      if (
+        hasArray &&
+        hasNonArray &&
+        SchemaIR.equals(Option.getOr(arrayItemType, Unknown), Option.getOr(nonArrayType, Unknown))
+      ) {
+        `S.array(${recurse(Option.getOr(arrayItemType, Unknown))})`
+      } else if (
+        types->Array.every(t =>
+          switch t {
+          | Literal(StringLiteral(_)) => true
+          | _ => false
+          }
+        ) &&
+        Array.length(types) > 0 &&
+        Array.length(types) <= 50
+      ) {
+        `S.union([${types->Array.map(recurse)->Array.join(", ")}])`
+      } else {
+        addWarning(
+          ctx,
+          ComplexUnionSimplified({
+            location: ctx.path,
+            types: types->Array.map(SchemaIR.toString)->Array.join(" | "),
+          }),
+        )
+        "S.json"
+      }
+    | Intersection(types) =>
+      if types->Array.every(t =>
+        switch t {
+        | Reference(_) => true
+        | _ => false
+        }
+      ) && Array.length(types) > 0 {
+        recurse(types->Array.get(Array.length(types) - 1)->Option.getOr(Unknown))
+      } else {
+        addWarning(
+          ctx,
+          IntersectionNotFullySupported({location: ctx.path, note: "Complex intersection"}),
+        )
+        "S.json"
+      }
+    | Reference(ref) =>
+      let schemaPath = switch ctx.availableSchemas {
+      | Some(available) =>
+        let name =
+          ref
+          ->String.split("/")
+          ->Array.get(ref->String.split("/")->Array.length - 1)
+          ->Option.getOr("")
+        available->Array.includes(name)
+          ? `${CodegenUtils.toPascalCase(name)}.schema`
+          : `ComponentSchemas.${CodegenUtils.toPascalCase(name)}.schema`
+      | None =>
+        ReferenceResolver.refToSchemaPath(
+          ~insideComponentSchemas=ctx.insideComponentSchemas,
+          ~modulePrefix=ctx.modulePrefix,
+          ref,
+        )->Option.getOr("S.json")
+      }
+      if schemaPath == "S.json" {
+        addWarning(
+          ctx,
+          FallbackToJson({
+            reason: `Unresolved ref: ${ref}`,
+            context: {path: ctx.path, operation: "gen ref", schema: None},
+          }),
+        )
+      }
+      schemaPath
+    | Option(inner) => `S.nullableAsOption(${recurse(inner)})`
+    | Unknown => "S.json"
+    }
+  }
+}
+
+let generateSchema = (
+  ~depth=0,
+  ~path="",
+  ~insideComponentSchemas=false,
+  ~availableSchemas=?,
+  ~modulePrefix="",
+  irType,
+) => {
+  let ctx = GenerationContext.make(~path, ~insideComponentSchemas, ~availableSchemas?, ~modulePrefix, ())
+  (generateSchemaWithContext(~ctx, ~depth, irType), ctx.warnings)
+}
+
+let generateNamedSchema = (
+  ~namedSchema: SchemaIR.namedSchema,
+  ~insideComponentSchemas=false,
+  ~availableSchemas=?,
+  ~modulePrefix="",
+) => {
+  let ctx = GenerationContext.make(
+    ~path=`schema.${namedSchema.name}`,
+    ~insideComponentSchemas,
+    ~availableSchemas?,
+    ~modulePrefix,
+    (),
+  )
+  let doc = switch namedSchema.description {
+  | Some(d) => CodegenUtils.generateDocComment(~description=d, ())
+  | None => ""
+  }
+  (
+    `${doc}let ${namedSchema.name}Schema = ${generateSchemaWithContext(~ctx, ~depth=0, namedSchema.type_)}`,
+    ctx.warnings,
+  )
+}
+
+let generateAllSchemas = (~context: SchemaIR.schemaContext) => {
+  let warnings = []
+  let schemas =
+    Dict.valuesToArray(context.schemas)
+    ->Array.toSorted((a, b) => String.compare(a.name, b.name))
+    ->Array.map(s => {
+      let (code, w) = generateNamedSchema(~namedSchema=s)
+      warnings->Array.pushMany(w)
+      code
+    })
+  (schemas, warnings)
+}