Schema.OperationCompilationTests.fs

module SwaggerProvider.Tests.Schema_OperationCompilationTests

/// Unit tests for the v3 OperationCompiler — verifying generated method signatures,
/// parameter ordering, CancellationToken injection, return-type resolution,
/// and async vs task mode.

open System
open System.Reflection
open System.Threading
open System.Threading.Tasks
open Microsoft.FSharp.Quotations
open Microsoft.FSharp.Quotations.ExprShape
open Microsoft.FSharp.Quotations.Patterns
open Xunit
open FsUnitTyped

// ── Helpers ───────────────────────────────────────────────────────────────────

let private compileTaskSchema schemaStr =
    compileV3Schema schemaStr false

let private compileAsyncSchema schemaStr =
    compileV3Schema schemaStr true

let private findMethod (types: ProviderImplementation.ProvidedTypes.ProvidedTypeDefinition list) (methodName: string) =
    types
    |> List.collect(fun t -> t.GetMethods() |> Array.toList)
    |> List.tryFind(fun m -> m.Name = methodName)

let private getInvokeCode(method: MethodInfo) =
    let providedMethod = method :?> ProviderImplementation.ProvidedTypes.ProvidedMethod

    let invokeCodeProp =
        providedMethod.GetType().GetProperty("GetInvokeCode", BindingFlags.Instance ||| BindingFlags.NonPublic)

    if isNull invokeCodeProp then
        failwith "GetInvokeCode property not found on ProvidedMethod"

    match invokeCodeProp.GetValue(providedMethod) :?> (Expr list -> Expr) option with
    | Some invokeCode -> invokeCode
    | None -> failwith $"Method '%s{method.Name}' has no invoke code"

let private letBoundVars expr =
    let rec loop expr =
        match expr with
        | Let(v, value, body) -> v :: (loop value @ loop body)
        | ShapeVar _ -> []
        | ShapeLambda(_, body) -> loop body
        | ShapeCombination(_, args) -> args |> List.collect loop

    loop expr

let private containsDuplicateVarObject vars =
    vars
    |> List.mapi(fun i v ->
        vars
        |> List.skip(i + 1)
        |> List.exists(fun other -> obj.ReferenceEquals(v, other)))
    |> List.exists id

// ── Simple GET with no parameters ─────────────────────────────────────────────

let private simpleGetSchema =
    """openapi: "3.0.0"
info:
  title: SimpleGetTest
  version: "1.0.0"
paths:
  /status:
    get:
      operationId: getStatus
      summary: Get server status
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
components:
  schemas: {}
"""

[<Fact>]
let ``GET endpoint generates a method with the operation name``() =
    let types = compileTaskSchema simpleGetSchema
    let method = findMethod types "GetStatus"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``GET endpoint with no parameters has CancellationToken as its only parameter``() =
    let types = compileTaskSchema simpleGetSchema
    let method = (findMethod types "GetStatus").Value
    let parameters = method.GetParameters()
    parameters.Length |> shouldEqual 1
    parameters[0].ParameterType |> shouldEqual typeof<CancellationToken>

[<Fact>]
let ``GET endpoint returning JSON string has Task<string> return type``() =
    let types = compileTaskSchema simpleGetSchema
    let method = (findMethod types "GetStatus").Value

    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<string>

// ── GET with required and optional path/query parameters ──────────────────────

let private parametrisedGetSchema =
    """openapi: "3.0.0"
info:
  title: ParameterisedGetTest
  version: "1.0.0"
paths:
  /items/{id}:
    get:
      operationId: getItem
      summary: Get item by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: tag
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``GET with required + optional params orders required before optional``() =
    let types = compileTaskSchema parametrisedGetSchema
    let method = (findMethod types "GetItem").Value
    let parameters = method.GetParameters()
    // Expected: id (required int64), tag (optional string), cancellationToken (CT)
    parameters.Length |> shouldEqual 3

    let idParam = parameters[0]
    let tagParam = parameters[1]
    let ctParam = parameters[2]

    idParam.Name |> shouldEqual "id"
    idParam.ParameterType |> shouldEqual typeof<int64>
    // optional — marked as optional via ParameterAttributes
    tagParam.Name |> shouldEqual "tag"
    tagParam.IsOptional |> shouldEqual true
    ctParam.ParameterType |> shouldEqual typeof<CancellationToken>

[<Fact>]
let ``CancellationToken is always the last parameter``() =
    let types = compileTaskSchema parametrisedGetSchema
    let method = (findMethod types "GetItem").Value
    let parameters = method.GetParameters()
    let last = parameters |> Array.last
    last.ParameterType |> shouldEqual typeof<CancellationToken>

// ── POST with JSON request body ───────────────────────────────────────────────

let private postWithBodySchema =
    """openapi: "3.0.0"
info:
  title: PostBodyTest
  version: "1.0.0"
paths:
  /items:
    post:
      operationId: createItem
      summary: Create a new item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewItem'
      responses:
        "201":
          description: Created
components:
  schemas:
    NewItem:
      type: object
      required:
        - name
      properties:
        name:
          type: string
"""

[<Fact>]
let ``POST with body generates method with body parameter before CancellationToken``() =
    let types = compileTaskSchema postWithBodySchema
    let method = (findMethod types "CreateItem").Value
    let parameters = method.GetParameters()
    // Expected: body (required NewItem), cancellationToken (CT)
    parameters.Length |> shouldEqual 2
    let bodyParam = parameters[0]
    let ctParam = parameters[1]
    // Body parameter is a provided type, so just verify it is not CancellationToken
    bodyParam.ParameterType |> shouldNotEqual typeof<CancellationToken>
    ctParam.ParameterType |> shouldEqual typeof<CancellationToken>

[<Fact>]
let ``POST with no response body has Task<unit> return type``() =
    let types = compileTaskSchema postWithBodySchema
    let method = (findMethod types "CreateItem").Value

    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    method.ReturnType.GetGenericArguments()[0] |> shouldEqual typeof<unit>

// ── CancellationToken naming collision avoidance ──────────────────────────────

let private ctCollisionSchema =
    """openapi: "3.0.0"
info:
  title: CTCollisionTest
  version: "1.0.0"
paths:
  /search:
    get:
      operationId: search
      parameters:
        - name: cancellationToken
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``when a query param is named cancellationToken the injected CT param gets a unique name``() =
    let types = compileTaskSchema ctCollisionSchema
    let method = (findMethod types "Search").Value
    let parameters = method.GetParameters()
    // There should be two parameters: the query param + the CT param
    parameters.Length |> shouldEqual 2
    let ctParam = parameters |> Array.last
    // The injected CT param must not collide with the API param name
    ctParam.ParameterType |> shouldEqual typeof<CancellationToken>
    ctParam.Name |> shouldNotEqual parameters[0].Name

// ── Multiple operations — each gets its own CT parameter ─────────────────────

let private multiOpSchema =
    """openapi: "3.0.0"
info:
  title: MultiOpTest
  version: "1.0.0"
paths:
  /pets:
    get:
      operationId: listPets
      responses:
        "200":
          description: OK
    post:
      operationId: createPet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Created
components:
  schemas: {}
"""

[<Fact>]
let ``multiple operations each generate a method with CancellationToken``() =
    let types = compileTaskSchema multiOpSchema

    let listPets = findMethod types "ListPets"
    let createPet = findMethod types "CreatePet"

    listPets.IsSome |> shouldEqual true
    createPet.IsSome |> shouldEqual true

    let listPetsParams = listPets.Value.GetParameters()
    let createPetParams = createPet.Value.GetParameters()

    (listPetsParams |> Array.last).ParameterType
    |> shouldEqual typeof<CancellationToken>

    (createPetParams |> Array.last).ParameterType
    |> shouldEqual typeof<CancellationToken>

// ── Async mode: asAsync=true returns Async<T> instead of Task<T> ──────────────

[<Fact>]
let ``asAsync=true: GET returning string produces Async<string> return type``() =
    let types = compileAsyncSchema simpleGetSchema
    let method = (findMethod types "GetStatus").Value

    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Async<_>>

    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<string>

[<Fact>]
let ``asAsync=true: POST with no response body produces Async<unit> return type``() =
    let types = compileAsyncSchema postWithBodySchema
    let method = (findMethod types "CreateItem").Value

    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Async<_>>

    method.ReturnType.GetGenericArguments()[0] |> shouldEqual typeof<unit>

[<Fact>]
let ``asAsync=true: method is still generated with correct name``() =
    let types = compileAsyncSchema simpleGetSchema
    let method = findMethod types "GetStatus"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``asAsync=true: CancellationToken is still the last parameter``() =
    let types = compileAsyncSchema parametrisedGetSchema
    let method = (findMethod types "GetItem").Value
    let parameters = method.GetParameters()

    (parameters |> Array.last).ParameterType
    |> shouldEqual typeof<CancellationToken>

// ── DELETE / PUT operations ──────────────────────────────────────────────────

let private deleteEndpointSchema =
    """openapi: "3.0.0"
info:
  title: DeleteTest
  version: "1.0.0"
paths:
  /items/{id}:
    delete:
      operationId: deleteItem
      summary: Delete an item
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: No Content
components:
  schemas: {}
"""

[<Fact>]
let ``DELETE endpoint generates a method``() =
    let types = compileTaskSchema deleteEndpointSchema
    let method = findMethod types "DeleteItem"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``DELETE endpoint with 204 response produces Task<unit> return type``() =
    let types = compileTaskSchema deleteEndpointSchema
    let method = (findMethod types "DeleteItem").Value

    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    method.ReturnType.GetGenericArguments()[0] |> shouldEqual typeof<unit>

[<Fact>]
let ``DELETE endpoint path parameter is included before CancellationToken``() =
    let types = compileTaskSchema deleteEndpointSchema
    let method = (findMethod types "DeleteItem").Value
    let parameters = method.GetParameters()
    // id (required int32) + cancellationToken
    parameters.Length |> shouldEqual 2
    parameters[0].Name |> shouldEqual "id"
    parameters[0].ParameterType |> shouldEqual typeof<int32>

    (parameters |> Array.last).ParameterType
    |> shouldEqual typeof<CancellationToken>

let private putEndpointSchema =
    """openapi: "3.0.0"
info:
  title: PutTest
  version: "1.0.0"
paths:
  /items/{id}:
    put:
      operationId: updateItem
      summary: Update an item
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItem'
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateItem'
components:
  schemas:
    UpdateItem:
      type: object
      required:
        - name
      properties:
        name:
          type: string
"""

[<Fact>]
let ``PUT endpoint generates a method``() =
    let types = compileTaskSchema putEndpointSchema
    let method = findMethod types "UpdateItem"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``PUT endpoint has path param and body param before CancellationToken``() =
    let types = compileTaskSchema putEndpointSchema
    let method = (findMethod types "UpdateItem").Value
    let parameters = method.GetParameters()
    // id (int64) + body (UpdateItem) + cancellationToken — 3 params total
    parameters.Length |> shouldEqual 3
    parameters[0].Name |> shouldEqual "id"
    parameters[0].ParameterType |> shouldEqual typeof<int64>
    // body param is a provided type (not CancellationToken)
    parameters[1].ParameterType
    |> shouldNotEqual typeof<CancellationToken>

    (parameters |> Array.last).ParameterType
    |> shouldEqual typeof<CancellationToken>

[<Fact>]
let ``PUT endpoint with JSON response produces Task<T> return type``() =
    let types = compileTaskSchema putEndpointSchema
    let method = (findMethod types "UpdateItem").Value

    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    // Return type must not be unit — should be the UpdateItem provided type
    method.ReturnType.GetGenericArguments()[0]
    |> shouldNotEqual typeof<unit>

// ── Header parameters ─────────────────────────────────────────────────────────

let private headerParamSchema =
    """openapi: "3.0.0"
info:
  title: HeaderParamTest
  version: "1.0.0"
paths:
  /items:
    get:
      operationId: listItems
      parameters:
        - name: X-Api-Version
          in: header
          required: true
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``header parameter is included as a method parameter``() =
    let types = compileTaskSchema headerParamSchema
    let method = (findMethod types "ListItems").Value
    let parameters = method.GetParameters()
    // xApiVersion (required string) + limit (optional int) + cancellationToken
    parameters.Length |> shouldEqual 3
    // Header param names are camelCased
    let paramNames = parameters |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "xApiVersion"

[<Fact>]
let ``required header parameter is not optional``() =
    let types = compileTaskSchema headerParamSchema
    let method = (findMethod types "ListItems").Value
    let parameters = method.GetParameters()
    let headerParam = parameters |> Array.find(fun p -> p.Name = "xApiVersion")
    headerParam.IsOptional |> shouldEqual false
    headerParam.ParameterType |> shouldEqual typeof<string>

// ── Cookie parameters ──────────────────────────────────────────────────────────

let private cookieParamSchema =
    """openapi: "3.0.0"
info:
  title: CookieParamTest
  version: "1.0.0"
paths:
  /session:
    get:
      operationId: getSession
      parameters:
        - name: sessionId
          in: cookie
          required: true
          schema:
            type: string
        - name: theme
          in: cookie
          required: false
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
components:
  schemas: {}
"""

[<Fact>]
let ``cookie parameter is included as a method parameter``() =
    let types = compileTaskSchema cookieParamSchema
    let method = (findMethod types "GetSession").Value
    let parameters = method.GetParameters()
    // sessionId (required string) + theme (optional string) + cancellationToken
    parameters.Length |> shouldEqual 3
    let paramNames = parameters |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "sessionId"
    paramNames |> shouldContain "theme"

[<Fact>]
let ``required cookie parameter is not optional``() =
    let types = compileTaskSchema cookieParamSchema
    let method = (findMethod types "GetSession").Value
    let parameters = method.GetParameters()
    let cookieParam = parameters |> Array.find(fun p -> p.Name = "sessionId")
    cookieParam.IsOptional |> shouldEqual false
    cookieParam.ParameterType |> shouldEqual typeof<string>

[<Fact>]
let ``optional cookie parameter is optional``() =
    let types = compileTaskSchema cookieParamSchema
    let method = (findMethod types "GetSession").Value
    let parameters = method.GetParameters()
    let themeParam = parameters |> Array.find(fun p -> p.Name = "theme")
    themeParam.IsOptional |> shouldEqual true

// ── text/plain response ────────────────────────────────────────────────────────

let private textPlainResponseSchema =
    """openapi: "3.0.0"
info:
  title: TextPlainTest
  version: "1.0.0"
paths:
  /health:
    get:
      operationId: getHealth
      responses:
        "200":
          description: OK
          content:
            text/plain:
              schema:
                type: string
components:
  schemas: {}
"""

[<Fact>]
let ``text/plain response produces Task<string> return type``() =
    let types = compileTaskSchema textPlainResponseSchema
    let method = (findMethod types "GetHealth").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<string>

[<Fact>]
let ``text/plain response in async mode produces Async<string> return type``() =
    let types = compileAsyncSchema textPlainResponseSchema
    let method = (findMethod types "GetHealth").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Async<_>>

    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<string>

// ── default response ───────────────────────────────────────────────────────────

let private defaultResponseSchema =
    """openapi: "3.0.0"
info:
  title: DefaultResponseTest
  version: "1.0.0"
paths:
  /data:
    get:
      operationId: getData
      responses:
        default:
          description: Default response
          content:
            application/json:
              schema:
                type: string
components:
  schemas: {}
"""

[<Fact>]
let ``default response is used as return type when no 2xx response is defined``() =
    let types = compileTaskSchema defaultResponseSchema
    let method = (findMethod types "GetData").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>
    // The string schema from the default response should produce Task<string>
    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<string>

// ── Multiple path parameters ───────────────────────────────────────────────────

let private multiplePathParamsSchema =
    """openapi: "3.0.0"
info:
  title: MultiplePathParamsTest
  version: "1.0.0"
paths:
  /users/{userId}/posts/{postId}:
    get:
      operationId: getUserPost
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
        - name: postId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
components:
  schemas: {}
"""

[<Fact>]
let ``both path parameters appear as required parameters``() =
    let types = compileTaskSchema multiplePathParamsSchema
    let method = (findMethod types "GetUserPost").Value
    let parameters = method.GetParameters()
    let paramNames = parameters |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "userId"
    paramNames |> shouldContain "postId"

[<Fact>]
let ``path parameters in nested path are required (not optional)``() =
    let types = compileTaskSchema multiplePathParamsSchema
    let method = (findMethod types "GetUserPost").Value
    let parameters = method.GetParameters()

    let userIdParam = parameters |> Array.find(fun p -> p.Name = "userId")
    userIdParam.IsOptional |> shouldEqual false

    let postIdParam = parameters |> Array.find(fun p -> p.Name = "postId")
    postIdParam.IsOptional |> shouldEqual false

[<Fact>]
let ``multiple path params appear before CancellationToken``() =
    let types = compileTaskSchema multiplePathParamsSchema
    let method = (findMethod types "GetUserPost").Value
    let parameters = method.GetParameters()
    let lastParam = parameters |> Array.last

    lastParam.ParameterType |> shouldEqual typeof<CancellationToken>

    parameters.Length |> shouldEqual 3 // userId, postId, CancellationToken

[<Fact>]
let ``invokeCode for multiple path params does not reuse the same quotation Var binding``() =
    let types = compileTaskSchema multiplePathParamsSchema
    let method = (findMethod types "GetUserPost").Value
    let invokeCode = getInvokeCode method

    let thisExpr = Expr.Var(Var("this", method.DeclaringType))
    let userIdExpr = Expr.Var(Var("userId", typeof<int32>))
    let postIdExpr = Expr.Var(Var("postId", typeof<int32>))
    let ctExpr = Expr.Var(Var("cancellationToken", typeof<CancellationToken>))

    let body = invokeCode [ thisExpr; userIdExpr; postIdExpr; ctExpr ]

    body
    |> letBoundVars
    |> containsDuplicateVarObject
    |> shouldEqual false

let private multipleQueryParamsSchema =
    """openapi: "3.0.0"
info:
  title: MultipleQueryParamsTest
  version: "1.0.0"
paths:
  /search:
    get:
      operationId: searchItems
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: page
          in: query
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
components:
  schemas: {}
"""

[<Fact>]
let ``invokeCode for multiple query params does not reuse the same quotation Var binding``() =
    let types = compileTaskSchema multipleQueryParamsSchema
    let method = (findMethod types "SearchItems").Value
    let invokeCode = getInvokeCode method

    let thisExpr = Expr.Var(Var("this", method.DeclaringType))
    let qExpr = Expr.Var(Var("q", typeof<string>))
    let pageExpr = Expr.Var(Var("page", typeof<int32>))
    let ctExpr = Expr.Var(Var("cancellationToken", typeof<CancellationToken>))

    let body = invokeCode [ thisExpr; qExpr; pageExpr; ctExpr ]

    body
    |> letBoundVars
    |> containsDuplicateVarObject
    |> shouldEqual false

// ── PATCH operation ────────────────────────────────────────────────────────────

let private patchSchema =
    """openapi: "3.0.0"
info:
  title: PatchTest
  version: "1.0.0"
paths:
  /items/{id}:
    patch:
      operationId: updateItem
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``PATCH endpoint generates a method``() =
    let types = compileTaskSchema patchSchema
    let method = findMethod types "UpdateItem"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``PATCH endpoint has path param, body param, and CancellationToken``() =
    let types = compileTaskSchema patchSchema
    let method = (findMethod types "UpdateItem").Value
    let parameters = method.GetParameters()
    let paramNames = parameters |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "id"
    paramNames |> shouldContain "json"
    let lastParam = parameters |> Array.last

    lastParam.ParameterType |> shouldEqual typeof<CancellationToken>

// ── Auto-generated operation name (no operationId) ─────────────────────────────

let private noOperationIdSchema =
    """openapi: "3.0.0"
info:
  title: NoOperationIdTest
  version: "1.0.0"
paths:
  /categories/{categoryId}/items:
    get:
      parameters:
        - name: categoryId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
components:
  schemas: {}
"""

[<Fact>]
let ``operation without operationId generates a method from path and HTTP method``() =
    let types = compileTaskSchema noOperationIdSchema
    let method = findMethod types "GetCategoryItems"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``operation without operationId has correct parameter count``() =
    let types = compileTaskSchema noOperationIdSchema
    // findMethod searches all methods on all types; just verify we find exactly one
    // method that has the expected signature (categoryId + CancellationToken)
    let allMethods =
        types
        |> List.collect(fun t -> t.GetMethods() |> Array.toList)
        |> List.filter(fun m ->
            let ps = m.GetParameters()

            ps.Length = 2
            && ps[0].Name = "categoryId"
            && ps[1].ParameterType = typeof<CancellationToken>)

    allMethods.Length |> shouldEqual 1

// ── application/x-www-form-urlencoded request body ────────────────────────────

let private formUrlEncodedBodySchema =
    """openapi: "3.0.0"
info:
  title: FormUrlEncodedTest
  version: "1.0.0"
paths:
  /login:
    post:
      operationId: login
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``form-urlencoded body generates a method``() =
    let types = compileTaskSchema formUrlEncodedBodySchema
    let method = findMethod types "Login"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``form-urlencoded body parameter is named formUrlEncoded``() =
    let types = compileTaskSchema formUrlEncodedBodySchema
    let method = (findMethod types "Login").Value
    let parameters = method.GetParameters()
    let paramNames = parameters |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "formUrlEncoded"

[<Fact>]
let ``form-urlencoded body has CancellationToken as last parameter``() =
    let types = compileTaskSchema formUrlEncodedBodySchema
    let method = (findMethod types "Login").Value
    let lastParam = method.GetParameters() |> Array.last
    lastParam.ParameterType |> shouldEqual typeof<CancellationToken>

// ── multipart/form-data request body ─────────────────────────────────────────

let private multipartFormDataBodySchema =
    """openapi: "3.0.0"
info:
  title: MultipartTest
  version: "1.0.0"
paths:
  /upload:
    post:
      operationId: uploadFile
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``multipart/form-data body generates a method``() =
    let types = compileTaskSchema multipartFormDataBodySchema
    let method = findMethod types "UploadFile"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``multipart/form-data body parameter is named formData``() =
    let types = compileTaskSchema multipartFormDataBodySchema
    let method = (findMethod types "UploadFile").Value
    let parameters = method.GetParameters()
    let paramNames = parameters |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "formData"

[<Fact>]
let ``multipart/form-data body has CancellationToken as last parameter``() =
    let types = compileTaskSchema multipartFormDataBodySchema
    let method = (findMethod types "UploadFile").Value
    let lastParam = method.GetParameters() |> Array.last
    lastParam.ParameterType |> shouldEqual typeof<CancellationToken>

// ── application/octet-stream request body ────────────────────────────────────

let private octetStreamBodySchema =
    """openapi: "3.0.0"
info:
  title: OctetStreamTest
  version: "1.0.0"
paths:
  /blob:
    post:
      operationId: uploadBlob
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: Created
components:
  schemas: {}
"""

[<Fact>]
let ``octet-stream body generates a method``() =
    let types = compileTaskSchema octetStreamBodySchema
    let method = findMethod types "UploadBlob"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``octet-stream body parameter is named octetStream``() =
    let types = compileTaskSchema octetStreamBodySchema
    let method = (findMethod types "UploadBlob").Value
    let parameters = method.GetParameters()
    let paramNames = parameters |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "octetStream"

[<Fact>]
let ``octet-stream body has CancellationToken as last parameter``() =
    let types = compileTaskSchema octetStreamBodySchema
    let method = (findMethod types "UploadBlob").Value
    let lastParam = method.GetParameters() |> Array.last
    lastParam.ParameterType |> shouldEqual typeof<CancellationToken>

// ── requestBody with no content entries (NoMediaType) ─────────────────────────

let private noMediaTypeBodySchema =
    """openapi: "3.0.0"
info:
  title: NoMediaTypeTest
  version: "1.0.0"
paths:
  /notify:
    post:
      operationId: sendNotification
      requestBody:
        required: true
        content: {}
      responses:
        "204":
          description: No content
components:
  schemas: {}
"""

[<Fact>]
let ``requestBody with empty content generates a method``() =
    let types = compileTaskSchema noMediaTypeBodySchema
    let method = findMethod types "SendNotification"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``requestBody with empty content adds a body parameter named noData``() =
    let types = compileTaskSchema noMediaTypeBodySchema
    let method = (findMethod types "SendNotification").Value
    let parameters = method.GetParameters()
    let paramNames = parameters |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "noData"

[<Fact>]
let ``requestBody with empty content has CancellationToken as last parameter``() =
    let types = compileTaskSchema noMediaTypeBodySchema
    let method = (findMethod types "SendNotification").Value
    let lastParam = method.GetParameters() |> Array.last
    lastParam.ParameterType |> shouldEqual typeof<CancellationToken>

let private controllerPrefixSchema =
    """openapi: "3.0.0"
info:
  title: ControllerTest
  version: "1.0.0"
paths:
  /pets:
    get:
      operationId: Pet_list
      responses:
        "200":
          description: OK
  /pets/{id}:
    get:
      operationId: Pet_get
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
  /users:
    get:
      operationId: User_list
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``ignoreControllerPrefix=false splits operations into per-controller client classes``() =
    let types = compileV3SchemaWithOptions controllerPrefixSchema false false false
    let typeNames = types |> List.map(fun t -> t.Name)
    // Pet_list and Pet_get go into Pet_Client; User_list goes into User_Client
    // (ReserveUniqueName "Pet" "Client" → "Pet_Client")
    typeNames |> shouldContain "Pet_Client"
    typeNames |> shouldContain "User_Client"

[<Fact>]
let ``ignoreControllerPrefix=false puts Pet operations on PetClient``() =
    let types = compileV3SchemaWithOptions controllerPrefixSchema false false false
    let petClient = types |> List.find(fun t -> t.Name = "Pet_Client")

    let methodNames =
        petClient.GetMethods() |> Array.map(fun m -> m.Name) |> Array.toList

    methodNames |> shouldContain "List"
    methodNames |> shouldContain "Get"

[<Fact>]
let ``ignoreControllerPrefix=false puts User operations on UserClient``() =
    let types = compileV3SchemaWithOptions controllerPrefixSchema false false false
    let userClient = types |> List.find(fun t -> t.Name = "User_Client")

    let methodNames =
        userClient.GetMethods() |> Array.map(fun m -> m.Name) |> Array.toList

    methodNames |> shouldContain "List"

[<Fact>]
let ``ignoreControllerPrefix=true puts all operations into a single Client class``() =
    let types = compileV3SchemaWithOptions controllerPrefixSchema true false false

    let clientTypes = types |> List.filter(fun t -> t.Name.EndsWith "Client")

    clientTypes.Length |> shouldEqual 1

// ── ignoreOperationId=true: method names generated from path ──────────────────

let private namedOperationSchema =
    """openapi: "3.0.0"
info:
  title: IgnoreOpIdTest
  version: "1.0.0"
paths:
  /pets:
    get:
      operationId: listAllPets
      responses:
        "200":
          description: OK
  /pets/{id}:
    get:
      operationId: getPetById
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``ignoreOperationId=true generates method name from path not operationId``() =
    let types = compileV3SchemaWithOptions namedOperationSchema true true false
    let allMethods = types |> List.collect(fun t -> t.GetMethods() |> Array.toList)
    let methodNames = allMethods |> List.map(fun m -> m.Name)
    // With ignoreOperationId=true, names come from HTTP method + path segments
    // GET /pets → GetPets, GET /pets/{id} → GetPet (singularized before path param)
    methodNames |> shouldContain "GetPets"

[<Fact>]
let ``ignoreOperationId=true does not generate the original operationId as method name``() =
    let types = compileV3SchemaWithOptions namedOperationSchema true true false
    let allMethods = types |> List.collect(fun t -> t.GetMethods() |> Array.toList)
    let methodNames = allMethods |> List.map(fun m -> m.Name)
    methodNames |> shouldNotContain "ListAllPets"
    methodNames |> shouldNotContain "GetPetById"

// ── Response types: $ref to component schema ──────────────────────────────────
// Verifies that when a response schema is a $ref to a component, the generated
// method's return type is Task<ComponentType> (not Task<unit> or Task<obj>).

let private refResponseSchema =
    """openapi: "3.0.0"
info:
  title: RefResponseTest
  version: "1.0.0"
paths:
  /pets/{id}:
    get:
      operationId: getPet
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        age:
          type: integer
"""

[<Fact>]
let ``GET returning component $ref produces Task<T> with a non-primitive type argument``() =
    let types = compileTaskSchema refResponseSchema
    let method = (findMethod types "GetPet").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    // The generic argument should not be unit, string, or any other primitive —
    // it should be the compiled Pet ProvidedType
    let returnArg = method.ReturnType.GetGenericArguments()[0]
    returnArg |> shouldNotEqual typeof<unit>
    returnArg |> shouldNotEqual typeof<obj>
    returnArg |> shouldNotEqual typeof<string>
    returnArg.Name |> shouldEqual "Pet"

[<Fact>]
let ``GET returning component $ref compiles the referenced schema as a named type``() =
    let types = compileTaskSchema refResponseSchema
    let typeNames = types |> List.map(fun t -> t.Name)
    typeNames |> shouldContain "Pet"

[<Fact>]
let ``GET returning component $ref: Pet type has the declared properties``() =
    let types = compileTaskSchema refResponseSchema
    let petType = types |> List.find(fun t -> t.Name = "Pet")
    let propNames = petType.GetProperties() |> Array.map(fun p -> p.Name)
    propNames |> shouldContain "Name"
    propNames |> shouldContain "Age"

// ── Response types: array of $ref to component schema ─────────────────────────
// Verifies that when a response schema is an array of $ref items, the method's
// return type is Task<ComponentType[]>.

let private arrayRefResponseSchema =
    """openapi: "3.0.0"
info:
  title: ArrayRefResponseTest
  version: "1.0.0"
paths:
  /pets:
    get:
      operationId: listPets
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
"""

[<Fact>]
let ``GET returning array-of-$ref produces Task<T[]> return type``() =
    let types = compileTaskSchema arrayRefResponseSchema
    let method = (findMethod types "ListPets").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    let returnArg = method.ReturnType.GetGenericArguments()[0]
    returnArg.IsArray |> shouldEqual true

[<Fact>]
let ``GET returning array-of-$ref: array element type is the component schema type``() =
    let types = compileTaskSchema arrayRefResponseSchema
    let method = (findMethod types "ListPets").Value
    let returnArg = method.ReturnType.GetGenericArguments()[0]
    returnArg.IsArray |> shouldEqual true
    returnArg.GetElementType().Name |> shouldEqual "Pet"

// ── Response types: POST returning created resource ───────────────────────────
// Verifies that POST with a 201 response body produces Task<ComponentType>.

let private postCreatedResponseSchema =
    """openapi: "3.0.0"
info:
  title: PostCreatedTest
  version: "1.0.0"
paths:
  /pets:
    post:
      operationId: createPet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPet'
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    NewPet:
      type: object
      required:
        - name
      properties:
        name:
          type: string
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string
"""

[<Fact>]
let ``POST with 201 response produces Task<T> (not Task<unit>)``() =
    let types = compileTaskSchema postCreatedResponseSchema
    let method = (findMethod types "CreatePet").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    let returnArg = method.ReturnType.GetGenericArguments()[0]
    returnArg |> shouldNotEqual typeof<unit>

[<Fact>]
let ``POST with 201 $ref response return type is the component schema type``() =
    let types = compileTaskSchema postCreatedResponseSchema
    let method = (findMethod types "CreatePet").Value
    let returnArg = method.ReturnType.GetGenericArguments()[0]
    returnArg.Name |> shouldEqual "Pet"

[<Fact>]
let ``POST with 201 response: request body param type is the NewPet component schema type``() =
    let types = compileTaskSchema postCreatedResponseSchema
    let method = (findMethod types "CreatePet").Value
    let parameters = method.GetParameters()
    // body param is first, CancellationToken last
    parameters.Length |> shouldEqual 2
    parameters[1].ParameterType |> shouldEqual typeof<CancellationToken>
    let bodyParam = parameters[0]
    bodyParam.ParameterType.Name |> shouldEqual "NewPet"

// ── text/plain request body ───────────────────────────────────────────────────

let private textPlainBodySchema =
    """openapi: "3.0.0"
info:
  title: TextPlainBodyTest
  version: "1.0.0"
paths:
  /echo:
    post:
      operationId: echoText
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
      responses:
        "200":
          description: OK
components:
  schemas: {}
"""

[<Fact>]
let ``text/plain request body generates a method``() =
    let types = compileTaskSchema textPlainBodySchema
    let method = findMethod types "EchoText"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``text/plain request body parameter is named textPlain``() =
    let types = compileTaskSchema textPlainBodySchema
    let method = (findMethod types "EchoText").Value
    let paramNames = method.GetParameters() |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "textPlain"

[<Fact>]
let ``text/plain request body has CancellationToken as last parameter``() =
    let types = compileTaskSchema textPlainBodySchema
    let method = (findMethod types "EchoText").Value
    let lastParam = method.GetParameters() |> Array.last
    lastParam.ParameterType |> shouldEqual typeof<CancellationToken>

// ── application/octet-stream response ────────────────────────────────────────

let private octetStreamResponseSchema =
    """openapi: "3.0.0"
info:
  title: OctetStreamResponseTest
  version: "1.0.0"
paths:
  /file:
    get:
      operationId: downloadFile
      responses:
        "200":
          description: File contents
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
components:
  schemas: {}
"""

[<Fact>]
let ``octet-stream response generates a method``() =
    let types = compileTaskSchema octetStreamResponseSchema
    let method = findMethod types "DownloadFile"
    method.IsSome |> shouldEqual true

[<Fact>]
let ``octet-stream response produces Task<IO.Stream> return type``() =
    let types = compileTaskSchema octetStreamResponseSchema
    let method = (findMethod types "DownloadFile").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<IO.Stream>

[<Fact>]
let ``octet-stream response has CancellationToken as its only parameter``() =
    let types = compileTaskSchema octetStreamResponseSchema
    let method = (findMethod types "DownloadFile").Value
    let parameters = method.GetParameters()
    parameters.Length |> shouldEqual 1
    parameters[0].ParameterType |> shouldEqual typeof<CancellationToken>

// ── Path-level parameters (inherited from PathItem) ───────────────────────────

let private pathLevelParamSchema =
    """openapi: "3.0.0"
info:
  title: PathLevelParamTest
  version: "1.0.0"
paths:
  /users/{userId}/posts:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: integer
    get:
      operationId: getUserPosts
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    post:
      operationId: createUserPost
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: string
      responses:
        "201":
          description: Created
components:
  schemas: {}
"""

[<Fact>]
let ``path-level parameter is inherited by GET operation``() =
    let types = compileTaskSchema pathLevelParamSchema
    let method = (findMethod types "GetUserPosts").Value
    let paramNames = method.GetParameters() |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "userId"

[<Fact>]
let ``path-level parameter is required with correct type``() =
    let types = compileTaskSchema pathLevelParamSchema
    let method = (findMethod types "GetUserPosts").Value
    let userIdParam = method.GetParameters() |> Array.find(fun p -> p.Name = "userId")
    userIdParam.ParameterType |> shouldEqual typeof<int32>
    userIdParam.IsOptional |> shouldEqual false

[<Fact>]
let ``path-level parameter is inherited by POST operation``() =
    let types = compileTaskSchema pathLevelParamSchema
    let method = (findMethod types "CreateUserPost").Value
    let paramNames = method.GetParameters() |> Array.map(fun p -> p.Name)
    paramNames |> shouldContain "userId"

// ── asAsync=true: octet-stream response produces Async<IO.Stream> ─────────────

let private octetStreamResponseAsyncSchema =
    """openapi: "3.0.0"
info:
  title: OctetStreamResponseAsyncTest
  version: "1.0.0"
paths:
  /download:
    get:
      operationId: downloadData
      responses:
        "200":
          description: File data
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
components:
  schemas: {}
"""

[<Fact>]
let ``asAsync=true: octet-stream response produces Async<IO.Stream> return type``() =
    let types = compileAsyncSchema octetStreamResponseAsyncSchema
    let method = (findMethod types "DownloadData").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Async<_>>

    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<IO.Stream>

// ── Non-200 2xx response used as return type ───────────────────────────────────
// The okResponse lookup in OperationCompiler falls back to any 2xx code when
// there is no explicit "200" response defined. These tests exercise that path.

let private created201ResponseSchema =
    """openapi: "3.0.0"
info:
  title: Created201Test
  version: "1.0.0"
paths:
  /items:
    post:
      operationId: createItem
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: string
components:
  schemas: {}
"""

[<Fact>]
let ``201 response with JSON body resolves to Task<string> when no 200 defined``() =
    let types = compileTaskSchema created201ResponseSchema
    let method = (findMethod types "CreateItem").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<string>

[<Fact>]
let ``201 response in async mode resolves to Async<string> when no 200 defined``() =
    let types = compileAsyncSchema created201ResponseSchema
    let method = (findMethod types "CreateItem").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Async<_>>

    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<string>

// ── 200 response takes priority over other 2xx when both are defined ─────────

/// OpenAPI 3.0 schema where an operation defines both a 200 (string) and a 201
/// (integer) response. The 200 response must win and determine the return type.
let private twoHundredAndCreatedSchema =
    """openapi: "3.0.0"
info:
  title: PriorityTest
  version: "1.0.0"
paths:
  /items:
    post:
      operationId: createItem
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: string
        "201":
          description: Created
          content:
            application/json:
              schema:
                type: integer
components:
  schemas: {}
"""

[<Fact>]
let ``200 response takes priority over 201 when both are defined``() =
    let types = compileTaskSchema twoHundredAndCreatedSchema
    let method = (findMethod types "CreateItem").Value
    method.ReturnType.IsGenericType |> shouldEqual true

    method.ReturnType.GetGenericTypeDefinition()
    |> shouldEqual typedefof<Task<_>>

    // 200 (string) must win over 201 (integer)
    method.ReturnType.GetGenericArguments()[0]
    |> shouldEqual typeof<string>

[<Fact>]
let ``200 response schema is used not 201 when both are present``() =
    // Verify that the 201 integer schema is not used when a 200 string schema is present.
    let types = compileTaskSchema twoHundredAndCreatedSchema
    let method = (findMethod types "CreateItem").Value
    let returnArg = method.ReturnType.GetGenericArguments()[0]
    returnArg |> shouldNotEqual typeof<int32>
    returnArg |> shouldEqual typeof<string>