@f3liz/rescript-autogen-openapi 0.3.1

package/src/generators/TypeScriptDtsGenerator.res

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// TypeScriptDtsGenerator.res - Generate TypeScript .d.ts definition files
+open Types
+
+let getFirstJsonSchema = (contentDict: dict<mediaType>): option<jsonSchema> =>
+  Dict.keysToArray(contentDict)
+  ->Array.get(0)
+  ->Option.flatMap(contentType => Dict.get(contentDict, contentType))
+  ->Option.flatMap(mediaType => mediaType.schema)
+
+let generateTypeScriptType = (name, description, schema) => {
+  let (irType, _) = SchemaIRParser.parseJsonSchema(schema)
+  IRToTypeScriptGenerator.generateNamedType(~namedSchema={name, description, type_: irType})
+}
+
+// Generate TypeScript interface for request type
+let generateRequestInterface = (~endpoint: endpoint, ~functionName) => {
+  let requestTypeName = `${CodegenUtils.toPascalCase(functionName)}Request`
+  endpoint.requestBody->Option.flatMap(body =>
+    getFirstJsonSchema(body.content)->Option.map(schema =>
+      generateTypeScriptType(requestTypeName, body.description, schema)
+    )
+  )
+}
+
+// Generate TypeScript interface for response type
+let generateResponseInterface = (~endpoint: endpoint, ~functionName) => {
+  let responseTypeName = `${CodegenUtils.toPascalCase(functionName)}Response`
+  let successCodes = ["200", "201", "202", "204"]
+  let successResponse = successCodes
+    ->Array.filterMap(code => Dict.get(endpoint.responses, code))
+    ->Array.get(0)
+
+  successResponse
+  ->Option.flatMap(response =>
+    response.content
+    ->Option.flatMap(getFirstJsonSchema)
+    ->Option.map(schema => generateTypeScriptType(responseTypeName, response.description->Some, schema))
+  )
+  ->Option.getOr(`export type ${responseTypeName} = void;`)
+}
+
+// Generate method signature for endpoint in an interface
+let generateMethodSignature = (~endpoint: endpoint, ~functionName) => {
+  let params = endpoint.requestBody->Option.isSome
+    ? `client: MisskeyClient, request: ${CodegenUtils.toPascalCase(functionName)}Request`
+    : "client: MisskeyClient"
+
+  let docLines = endpoint.summary->Option.mapOr([], summary => {
+    let lines = ["  /**", `   * ${summary}`]
+    endpoint.description->Option.forEach(description => {
+      if description != summary {
+        lines->Array.push(`   * ${description}`)
+      }
+    })
+    lines->Array.push("   */")
+    lines
+  })
+
+  let code = `
+    |${docLines->Array.join("\n")}
+    |  ${functionName}(${params}): Promise<${CodegenUtils.toPascalCase(functionName)}Response>;`
+  
+  code->CodegenUtils.trimMargin
+}
+
+// Generate .d.ts file for a module (grouped by tag)
+let generateModuleDts = (~moduleName, ~endpoints: array<endpoint>) => {
+  let interfaces =
+    endpoints
+    ->Array.map(endpoint => {
+      let functionName = CodegenUtils.generateOperationName(
+        endpoint.operationId,
+        endpoint.path,
+        endpoint.method,
+      )
+      let requestPart =
+        generateRequestInterface(~endpoint, ~functionName)->Option.getOr("")
+      let responsePart = generateResponseInterface(~endpoint, ~functionName)
+      [requestPart, responsePart]->Array.filter(s => s != "")->Array.join("\n")
+    })
+    ->Array.join("\n\n")
+
+  let methodSignatures =
+    endpoints
+    ->Array.map(endpoint =>
+      generateMethodSignature(
+        ~endpoint,
+        ~functionName=CodegenUtils.generateOperationName(
+          endpoint.operationId,
+          endpoint.path,
+          endpoint.method,
+        ),
+      )
+    )
+    ->Array.join("\n")
+
+  let header = `
+    |// TypeScript definitions for ${moduleName}
+    |// Generated by @f3liz/rescript-autogen-openapi
+    |// DO NOT EDIT
+    |
+    |import { MisskeyClient } from './index';
+    |import * as ComponentSchemas from './ComponentSchemas';
+    |`->CodegenUtils.trimMargin
+
+  `
+    |${header}
+    |
+    |${interfaces}
+    |
+    |export interface ${moduleName}Module {
+    |${methodSignatures}
+    |}
+    |
+    |export const ${moduleName}: ${moduleName}Module;
+    |`->CodegenUtils.trimMargin
+}
+
+// Generate ComponentSchemas.d.ts
+let generateComponentSchemasDts = (~schemas: Dict.t<jsonSchema>) => {
+  let content =
+    Dict.toArray(schemas)
+    ->Array.map(((name, schema)) => generateTypeScriptType(name, schema.description, schema))
+    ->Array.join("\n\n")
+
+  `
+    |// TypeScript definitions for ComponentSchemas
+    |// Generated by @f3liz/rescript-autogen-openapi
+    |// DO NOT EDIT
+    |
+    |${content}
+    |`->CodegenUtils.trimMargin
+}
+
+// Generate main index.d.ts with MisskeyClient class
+let generateIndexDts = (~moduleNames) => {
+  let imports = moduleNames->Array.map(m => `import { ${m}Module } from './${m}';`)->Array.join("\n")
+  let exports = moduleNames->Array.map(m => `export const ${m}: ${m}Module;`)->Array.join("\n")
+
+  `
+    |// TypeScript definitions
+    |// Generated by @f3liz/rescript-autogen-openapi
+    |// DO NOT EDIT
+    |
+    |${imports}
+    |
+    |export class MisskeyClient {
+    |  constructor(baseUrl: string, token?: string);
+    |  readonly baseUrl: string;
+    |  readonly token?: string;
+    |}
+    |
+    |${exports}
+    |`->CodegenUtils.trimMargin
+}
+
+// Generate all .d.ts files for a spec
+let generate = (~spec: openAPISpec, ~endpoints, ~outputDir): Pipeline.generationOutput => {
+  let endpointsByTag = OpenAPIParser.groupByTag(endpoints)
+  let moduleNames = []
+  let files =
+    Dict.toArray(endpointsByTag)
+    ->Array.filterMap(((tag, tagEndpoints)) =>
+      if Array.length(tagEndpoints) > 0 {
+        let name = CodegenUtils.toPascalCase(tag)
+        moduleNames->Array.push(name)
+        Some({
+          FileSystem.path: FileSystem.makePath(outputDir, `types/${name}.d.ts`),
+          content: generateModuleDts(~moduleName=name, ~endpoints=tagEndpoints),
+        })
+      } else {
+        None
+      }
+    )
+
+  spec.components
+  ->Option.flatMap(c => c.schemas)
+  ->Option.forEach(schemas =>
+    files->Array.push({
+      path: FileSystem.makePath(outputDir, "types/ComponentSchemas.d.ts"),
+      content: generateComponentSchemasDts(~schemas=schemas),
+    })
+  )
+
+  files->Array.push({
+    path: FileSystem.makePath(outputDir, "types/index.d.ts"),
+    content: generateIndexDts(~moduleNames),
+  })
+
+  {files, warnings: []}
+}

package/src/generators/TypeScriptWrapperGenerator.res

@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// TypeScriptWrapperGenerator.res - Generate TypeScript/JavaScript wrapper
+open Types
+
+let misskeyClientJsCode = `
+  |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();
+  |  }
+  |}`->CodegenUtils.trimMargin
+
+let generateWrapperMjs = (~endpoints, ~generatedModulePath) => {
+  let endpointsByTag = OpenAPIParser.groupByTag(endpoints)
+  let tags = Dict.keysToArray(endpointsByTag)
+
+  let imports =
+    tags
+    ->Array.map(tag => {
+      let moduleName = CodegenUtils.toPascalCase(tag)
+      `import * as ${moduleName} from '${generatedModulePath}/${moduleName}.mjs';`
+    })
+    ->Array.join("\n")
+
+  let wrappers =
+    tags
+    ->Array.map(tag => {
+      let moduleName = CodegenUtils.toPascalCase(tag)
+      let methods =
+        Dict.get(endpointsByTag, tag)
+        ->Option.getOr([])
+        ->Array.map(endpoint => {
+          let functionName = CodegenUtils.generateOperationName(
+            endpoint.operationId,
+            endpoint.path,
+            endpoint.method,
+          )
+          let hasRequestBody = endpoint.requestBody->Option.isSome
+          let bodyArg = hasRequestBody ? "body: request, " : ""
+          `
+            |  async ${functionName}(client${hasRequestBody ? ", request" : ""}) {
+            |    return ${moduleName}.${functionName}({
+            |      ${bodyArg}fetch: (url, method, body) => client._fetch(url, method, body)
+            |    });
+            |  },`
+        })
+        ->Array.join("\n")
+      `
+        |export const ${moduleName} = {
+        |${methods}
+        |};`
+    })
+    ->Array.join("\n\n")
+
+  `
+    |// Generated wrapper
+    |${imports}
+    |
+    |${misskeyClientJsCode}
+    |
+    |${wrappers}
+    |`->CodegenUtils.trimMargin
+}
+
+let generateWrapperDts = (~endpoints) => {
+  let endpointsByTag = OpenAPIParser.groupByTag(endpoints)
+  let tags = Dict.keysToArray(endpointsByTag)
+
+  let imports =
+    tags
+    ->Array.map(tag => {
+      let moduleName = CodegenUtils.toPascalCase(tag)
+      let typesToImport =
+        Dict.get(endpointsByTag, tag)
+        ->Option.getOr([])
+        ->Array.flatMap(endpoint => {
+          let pascalName = CodegenUtils.toPascalCase(
+            CodegenUtils.generateOperationName(endpoint.operationId, endpoint.path, endpoint.method),
+          )
+          if endpoint.requestBody->Option.isSome {
+            [`  ${pascalName}Request,`, `  ${pascalName}Response,`]
+          } else {
+            [`  ${pascalName}Response,`]
+          }
+        })
+        ->Array.join("\n")
+      `import type {
+${typesToImport}
+} from '../types/${moduleName}.d.ts';`
+    })
+    ->Array.join("\n")
+
+  let namespaces =
+    tags
+    ->Array.map(tag => {
+      let moduleName = CodegenUtils.toPascalCase(tag)
+      let functions =
+        Dict.get(endpointsByTag, tag)
+        ->Option.getOr([])
+        ->Array.map(endpoint => {
+          let functionName = CodegenUtils.generateOperationName(
+            endpoint.operationId,
+            endpoint.path,
+            endpoint.method,
+          )
+          let pascalName = CodegenUtils.toPascalCase(functionName)
+          let docComment = endpoint.summary->Option.mapOr("", summary => {
+            let descriptionPart = endpoint.description->Option.mapOr("", description =>
+              description == summary ? "" : " - " ++ description
+            )
+            `  /** ${summary}${descriptionPart} */\n`
+          })
+          let requestParam = endpoint.requestBody->Option.isSome ? `, request: ${pascalName}Request` : ""
+          `${docComment}  export function ${functionName}(client: MisskeyClient${requestParam}): Promise<${pascalName}Response>;`
+        })
+        ->Array.join("\n")
+      `
+        |export namespace ${moduleName} {
+        |${functions}
+        |}`
+    })
+    ->Array.join("\n\n")
+
+  `
+    |// Generated TypeScript definitions for wrapper
+    |${imports}
+    |
+    |export class MisskeyClient {
+    |  constructor(baseUrl: string, token?: string);
+    |  readonly baseUrl: string;
+    |  readonly token?: string;
+    |}
+    |
+    |${namespaces}
+    |`->CodegenUtils.trimMargin
+}
+
+let generate = (~endpoints, ~outputDir, ~generatedModulePath="../generated") => {
+  Pipeline.fromFilesAndWarnings(
+    [
+      {
+        FileSystem.path: FileSystem.makePath(outputDir, "wrapper/index.mjs"),
+        content: generateWrapperMjs(~endpoints, ~generatedModulePath),
+      },
+      {
+        path: FileSystem.makePath(outputDir, "wrapper/index.d.ts"),
+        content: generateWrapperDts(~endpoints),
+      },
+    ],
+    [],
+  )
+}

package/src/types/CodegenError.res

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// Error.res - Compact error and warning types with helpers
+
+// Error context for debugging (defined here to avoid circular dependency)
+@genType
+type context = {
+  path: string,
+  operation: string,
+  schema: option<JSON.t>, // Use JSON.t to avoid circular dependency with Types.jsonSchema
+}
+
+// Structured error types (keep original names for backward compat)
+@genType
+type t =
+  | SpecResolutionError({url: string, message: string})
+  | SchemaParseError({context: context, reason: string})
+  | ReferenceError({ref: string, context: context})
+  | 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<context>})
+
+// Warning types
+module Warning = {
+  @genType
+  type t =
+    | FallbackToJson({reason: string, context: context})
+    | 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})
+
+  let toString = w =>
+    switch w {
+    | FallbackToJson({reason, context}) =>
+      `⚠️  Falling back to JSON.t at '${context.path}' (${context.operation}): ${reason}`
+    | UnsupportedFeature({feature, fallback, location}) =>
+      `⚠️  Unsupported feature '${feature}' at '${location}', using fallback: ${fallback}`
+    | DepthLimitReached({depth, path}) =>
+      `⚠️  Depth limit ${depth->Int.toString} reached at '${path}', using simplified type`
+    | MissingSchema({ref, location}) =>
+      `⚠️  Schema reference '${ref}' not found at '${location}'`
+    | IntersectionNotFullySupported({location, note}) =>
+      `⚠️  Intersection type at '${location}' not fully supported: ${note}`
+    | ComplexUnionSimplified({location, types}) =>
+      `⚠️  Complex union at '${location}' simplified (types: ${types})`
+    }
+
+  let print = warnings =>
+    if Array.length(warnings) > 0 {
+      Console.log("\n⚠️  Warnings:")
+      warnings->Array.forEach(w => Console.log(toString(w)))
+    }
+}
+
+// Error helpers
+let toString = e =>
+  switch e {
+  | SpecResolutionError({url, message}) => `Failed to resolve spec from '${url}': ${message}`
+  | SchemaParseError({context, reason}) =>
+    `Failed to parse schema at '${context.path}' (${context.operation}): ${reason}`
+  | ReferenceError({ref, context}) =>
+    `Failed to resolve reference '${ref}' at '${context.path}' (${context.operation})`
+  | ValidationError({schema, issues}) =>
+    `Validation failed for schema '${schema}': ${issues->Array.join(", ")}`
+  | CircularSchemaError({ref, depth, path}) =>
+    `Circular schema detected for '${ref}' at depth ${depth->Int.toString} (path: ${path})`
+  | FileWriteError({filePath, message}) => `Failed to write file '${filePath}': ${message}`
+  | InvalidConfigError({field, message}) => `Invalid configuration for field '${field}': ${message}`
+  | UnknownError({message, context}) =>
+    switch context {
+    | Some(ctx) => `Unknown error at '${ctx.path}' (${ctx.operation}): ${message}`
+    | None => `Unknown error: ${message}`
+    }
+  }
+
+// Create context helper
+let makeContext = (~path, ~operation, ~schema=?, ()) => {
+  path,
+  operation,
+  schema,
+}

package/src/types/Config.res

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// Config.res - Generation configuration types
+
+@genType
+type generationStrategy =
+  | Separate
+  | SharedBase
+
+@genType
+type breakingChangeHandling =
+  | Error
+  | Warn
+  | Ignore
+
+@genType
+type forkSpecConfig = {
+  name: string,
+  specPath: string,
+}
+
+@genType
+type generationTargets = {
+  rescriptApi: bool,              // Generate base ReScript API (always true by default)
+  rescriptWrapper: bool,          // Generate ReScript thin wrapper (pipe-first)
+  typescriptDts: bool,            // Generate .d.ts type definitions
+  typescriptWrapper: bool,        // Generate TypeScript/JavaScript wrapper
+}
+
+@genType
+type t = {
+  specPath: string,
+  forkSpecs: option<array<forkSpecConfig>>,
+  outputDir: string,
+  strategy: generationStrategy,
+  modulePerTag: bool,
+  includeTags: option<array<string>>,
+  excludeTags: option<array<string>>,
+  generateDiffReport: bool,
+  breakingChangeHandling: breakingChangeHandling,
+  generateDocOverrides: option<bool>,
+  docOverrideDir: option<string>,
+  targets: option<generationTargets>,  // Generation targets (what to generate)
+  dtsOutputDir: option<string>,        // Output directory for .d.ts files (default: "types")
+  wrapperOutputDir: option<string>,    // Output directory for wrapper files (default: "wrapper")
+  baseInstanceName: option<string>,    // Subdirectory name for base instance (e.g., "misskey-io")
+  baseModulePrefix: option<string>,    // Module prefix for base instance (e.g., "MisskeyIo")
+}
+
+// Default configuration
+@genType
+let make = (
+  ~specPath,
+  ~outputDir,
+  ~strategy=SharedBase,
+  ~modulePerTag=true,
+  ~includeTags=?,
+  ~excludeTags=?,
+  ~generateDiffReport=true,
+  ~breakingChangeHandling=Warn,
+  ~forkSpecs=?,
+  ~generateDocOverrides=?,
+  ~docOverrideDir=?,
+  ~targets=?,
+  ~dtsOutputDir=?,
+  ~wrapperOutputDir=?,
+  ~baseInstanceName=?,
+  ~baseModulePrefix=?,
+  (),
+) => {
+  specPath,
+  outputDir,
+  strategy,
+  modulePerTag,
+  includeTags,
+  excludeTags,
+  generateDiffReport,
+  breakingChangeHandling,
+  forkSpecs,
+  generateDocOverrides,
+  docOverrideDir,
+  targets,
+  dtsOutputDir,
+  wrapperOutputDir,
+  baseInstanceName,
+  baseModulePrefix,
+}
+
+// Default generation targets
+let defaultTargets = (): generationTargets => {
+  rescriptApi: true,
+  rescriptWrapper: false,
+  typescriptDts: false,
+  typescriptWrapper: false,
+}

package/src/types/GenerationContext.res

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MPL-2.0
+
+// GenerationContext.res - Shared context type for IR code generators
+
+// Extracted auxiliary type that was too complex to inline
+type extractedType = {
+  typeName: string,
+  irType: SchemaIR.irType,
+  isUnboxed: bool, // Needs @unboxed annotation (for variant types from mixed unions)
+}
+
+type t = {
+  mutable warnings: array<CodegenError.Warning.t>,
+  mutable extractedTypes: array<extractedType>,
+  mutable extractCounter: int,
+  path: string,
+  insideComponentSchemas: bool, // Whether we're generating inside ComponentSchemas module
+  availableSchemas: option<array<string>>, // Schemas available in current module (for fork schemas)
+  modulePrefix: string, // Module prefix for qualified references (e.g., "MisskeyIo")
+  selfRefName: option<string>, // Schema name for self-referential type detection (e.g., "DriveFolder")
+}
+
+let make = (~path, ~insideComponentSchemas=false, ~availableSchemas=?, ~modulePrefix="", ~selfRefName=?, ()): t => {
+  warnings: [],
+  extractedTypes: [],
+  extractCounter: 0,
+  path,
+  insideComponentSchemas,
+  availableSchemas,
+  modulePrefix,
+  selfRefName,
+}
+
+let addWarning = (ctx: t, warning: CodegenError.Warning.t): unit => {
+  ctx.warnings->Array.push(warning)
+}
+
+let extractType = (ctx: t, ~baseName: string, ~isUnboxed=false, irType: SchemaIR.irType): string => {
+  // Check if this irType was already extracted (avoid duplicates)
+  let existing = ctx.extractedTypes->Array.find(({irType: existingIr}: extractedType) =>
+    SchemaIR.equals(existingIr, irType)
+  )
+  switch existing {
+  | Some({typeName}) => typeName
+  | None =>
+    ctx.extractCounter = ctx.extractCounter + 1
+    // ReScript type names must start with lowercase
+    let lowerBaseName = switch baseName->String.charAt(0) {
+    | "" => "extracted"
+    | first => first->String.toLowerCase ++ baseName->String.sliceToEnd(~start=1)
+    }
+    let typeName = `${lowerBaseName}_${Int.toString(ctx.extractCounter)}`
+    ctx.extractedTypes->Array.push({typeName, irType, isUnboxed})
+    typeName
+  }
+}