codegen

type AdditionalImport struct {
	Alias   string `yaml:"alias,omitempty"`
	Package string `yaml:"package"`
}

type Client struct {
	Name    string        `yaml:"name"`
	Timeout time.Duration `yaml:"timeout"`
}

type Configuration struct {
	PackageName     string  `yaml:"package"`
	CopyrightHeader string  `yaml:"copyright-header"`
	SkipPrune       bool    `yaml:"skip-prune"`
	Output          *Output `yaml:"output"`

	Generate *GenerateOptions `yaml:"generate"`
	Filter   FilterConfig     `yaml:"filter,omitempty"`
	Overlay  *OverlayOptions  `yaml:"overlay,omitempty"`

	AdditionalImports []AdditionalImport `yaml:"additional-imports,omitempty"`
	ErrorMapping      map[string]string  `yaml:"error-mapping,omitempty"`
	Client            *Client            `yaml:"client,omitempty"`

	UserTemplates map[string]string `yaml:"user-templates,omitempty"`
	UserContext   map[string]any    `yaml:"user-context,omitempty"`

	// BasePath is the directory used to resolve relative $ref file references.
	// When set, external file references like './common.yaml#/...' will be resolved
	// relative to this directory. Typically set to the directory containing the spec file.
	BasePath string `yaml:"base-path,omitempty"`
}

type Constraints struct {
	Required       *bool
	Nullable       *bool
	ReadOnly       *bool
	WriteOnly      *bool
	MinLength      *int64
	MaxLength      *int64
	Pattern        *string
	Min            *float64
	Max            *float64
	MinItems       *int64
	MaxItems       *int64
	MinProperties  *int64
	MaxProperties  *int64
	ValidationTags []string

	// RequiredKey is set for an object property listed in required: its key is written even when
	// nil, as null. Required only drives the validator tag, which some types drop. readOnly and
	// writeOnly properties don't count, as each is left out of one direction.
	RequiredKey bool
}

type ConstraintsContext struct {
	// contains filtered or unexported fields
}

type Discriminator struct {
	// maps discriminator value to go type
	Mapping map[string]string

	// JSON property name that holds the discriminator
	Property string
}

type EnumContext struct {
	Enums       []EnumDefinition
	Imports     []string
	Config      Configuration
	WithHeader  bool
	TypeTracker *TypeTracker
}

type EnumDefinition struct {
	Name           string
	ValueWrapper   string
	PrefixTypeName bool
	Schema         GoSchema
	Values         []EnumValue
	SpecLocation   SpecLocation
}

type EnumValue struct {
	Name  string
	Value string
}

type FieldDescriptor struct {
	Required bool   // Is the schema required? If not, we'll pass by pointer
	GoType   string // The Go type needed to represent the json type.
	GoName   string // The Go compatible type name for the type
	JsonName string // The json type name for the type
	IsRef    bool   // Is this schema a reference to predefined object?
}

type FilterConfig struct {
	Include FilterParamsConfig `yaml:"include"`
	Exclude FilterParamsConfig `yaml:"exclude"`
}

type FilterParamsConfig struct {
	Paths            []string            `yaml:"paths"`
	Tags             []string            `yaml:"tags"`
	OperationIDs     []string            `yaml:"operation-ids"`
	Webhooks         []string            `yaml:"webhooks"`
	SchemaProperties map[string][]string `yaml:"schema-properties"`
	Extensions       []string            `yaml:"extensions"`
}

type GenerateOptions struct {
	// Client specifies whether to generate the classic client - one method
	// per operation that returns the picked 2xx body type directly (e.g.
	// `func (c *Client) UploadDocument(...) (*DocumentStored, error)`).
	// Use this when callers only need the response body and the operation
	// has a single documented success status. Headers and non-picked 2xx
	// bodies are not exposed by this style; for that, use
	// ClientWithResponse instead, or both together.
	//
	// Combinations with ClientWithResponse:
	//   - client: true, client-with-response: false → classic only
	//   - client: false, client-with-response: true → envelope only
	//   - client: true, client-with-response: true  → both styles, combined
	//                                                 into a single ClientInterface
	//
	// Defaults to false.
	Client bool `yaml:"client"`

	// ClientWithResponse specifies whether to generate `<Op>WithResponse`
	// sibling functions that return a typed envelope: one `JSON<status>`
	// field per documented response, one `Headers<status>` typed struct per
	// status that declares headers, plus `HTTPResponse *http.Response` for
	// raw access (undocumented headers, status string, etc.). Use this when
	// an operation has multiple 2xx statuses with different bodies (e.g.
	// 201 sync + 202 queued), or when callers need typed access to headers
	// like Location or Retry-After.
	//
	// Additive to Client: when both flags are true, the generated
	// ClientInterface lists both `<Op>` and `<Op>WithResponse` methods so a
	// single mock or test double covers both shapes.
	//
	// Defaults to false.
	ClientWithResponse bool `yaml:"client-with-response"`

	// ClientStreaming adds a `<Op>Stream` sibling for every operation with a
	// sequential success response (SSE, NDJSON), returning a live
	// `runtime.Stream[T]`. Non-streaming methods keep their media type and
	// signatures, so an operation offering both `application/json` and
	// `text/event-stream` exposes both shapes.
	//
	// Off by default: the siblings add methods to the generated client
	// interface, which would break hand-written mocks on upgrade.
	ClientStreaming bool `yaml:"client-streaming"`

	// Models specifies whether to generate model types. Defaults to true.
	// Set to false when models are generated in a separate package.
	Models *bool `yaml:"models,omitempty"`

	// Handler specifies options for handler/server code generation.
	// If nil, no handler code is generated.
	Handler *HandlerOptions `yaml:"handler,omitempty"`

	// MCPServer specifies options for MCP (Model Context Protocol) server generation.
	// If set, generates MCP tools that wrap the generated client for AI assistant integration.
	// Requires client generation to be enabled.
	MCPServer *MCPServerOptions `yaml:"mcp-server,omitempty"`

	// OmitDescription specifies whether to omit schema description from the spec in the generated code. Defaults to false.
	OmitDescription bool `yaml:"omit-description"`

	// DefaultIntType specifies the default integer type to use. Defaults to "int".
	DefaultIntType string `yaml:"default-int-type"`

	// AlwaysPrefixEnumValues specifies whether to always prefix enum values with the schema name. Defaults to true.
	AlwaysPrefixEnumValues bool `yaml:"always-prefix-enum-values"`

	// AdditionalTags specifies additional struct tags to emit on generated fields,
	// mirroring the json tag value. For example, ["yaml"] emits yaml:"field_name,omitempty"
	// alongside the json tag. Per-property x-oapi-codegen-extra-tags take priority.
	AdditionalTags []string `yaml:"additional-tags"`

	// Validation specifies options for Validate() method generation.
	Validation ValidationOptions `yaml:"validation"`
}

type GeneratedCode map[string]string

type GoSchema struct {
	GoType                   string
	RefType                  string
	ArrayType                *GoSchema
	EnumValues               map[string]string
	Properties               []Property
	HasAdditionalProperties  bool
	AdditionalPropertiesType *GoSchema
	AdditionalTypes          []TypeDefinition
	SkipOptionalPointer      bool
	Description              string
	Constraints              Constraints

	UnionElements []UnionElement
	Discriminator *Discriminator
	// True if this schema is a struct wrapper around a union (embedded Either or union field)
	IsUnionWrapper bool

	// True if this union was generated from an if/then/else schema.
	// Uses runtime.Conditional instead of runtime.Either.
	IsConditional bool

	DefineViaAlias   bool
	IsPrimitiveAlias bool
	OpenAPISchema    *base.Schema
}

type HandlerKind string

type HandlerOptions struct {
	// Name is the name of the service interface. Defaults to "Service".
	Name string `yaml:"name"`

	// Kind specifies the router/framework to generate for. Defaults to "chi".
	// Supported values: "chi"
	Kind HandlerKind `yaml:"kind"`

	// Validation specifies options for request/response validation in handlers.
	Validation HandlerValidation `yaml:"validation"`

	// ModelsPackage specifies the package that model types live in, when they
	// are generated separately from the handler (generate.models: false) and
	// into a different package. Model type references in the generated
	// handler (request/response types, path/query/header/body params) are
	// qualified with its alias, and its import is added automatically.
	//
	// Requires generate.models: false, and both generation runs must be
	// given the same spec, filters, and error-mapping.
	ModelsPackage *ModelsPackage `yaml:"models-package"`

	// HandlerPackageAlias is the package alias used to reference the
	// generated handler code from the service scaffold (service.go), when
	// the scaffold is generated into its own package via
	// generate.handler.output. Example: "server" produces
	// "server.ServiceInterface" in service.go.
	//
	// This does not affect model type references - use ModelsPackage for
	// that. It replaces the misleadingly named ModelsPackageAlias.
	HandlerPackageAlias string `yaml:"handler-package-alias"`

	// ModelsPackageAlias is the package alias used to reference the
	// generated handler code from the service scaffold.
	//
	// Deprecated: use HandlerPackageAlias. Despite the name, this was never
	// the package models live in - it's the package the generated handler
	// itself is in, as seen from service.go. Kept only as a fallback: if
	// HandlerPackageAlias is unset, its value is used.
	ModelsPackageAlias string `yaml:"models-package-alias"`

	// MultipartMaxMemory is the maximum memory in MB for multipart form parsing.
	// Defaults to 32MB (matching Go stdlib). Files exceeding this are stored in temp files.
	MultipartMaxMemory int `yaml:"multipart-max-memory"`

	// Output specifies output for scaffolded handler files (service.go, middleware.go).
	// Falls back to root output if nil.
	Output *ScaffoldOutput `yaml:"output"`

	// Service specifies options for generating service.go scaffold.
	// If nil, no service scaffold is generated.
	Service *ServiceOptions `yaml:"service"`

	// Middleware specifies options for generating middleware.go.
	// If nil, no middleware is generated.
	Middleware *MiddlewareOptions `yaml:"middleware"`

	// Server specifies options for generating a runnable server main.go.
	// If nil, no server is generated.
	Server *ServerOptions `yaml:"server"`
}

type HandlerValidation struct {
	// Request enables validation of incoming requests. Defaults to false.
	Request bool `yaml:"request"`

	// Response enables validation of outgoing responses. Defaults to false.
	// Useful for contract testing.
	Response bool `yaml:"response"`
}

type MCPExtension struct {
	// Skip excludes this operation from MCP tool generation.
	// nil means not set (use default behavior), true means skip, false means include.
	Skip *bool `json:"skip,omitempty" yaml:"skip,omitempty"`

	// Name overrides the MCP tool name (default: operationId)
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Description overrides the MCP tool description (default: operation summary)
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
}

type MCPServerOptions struct {
	// DefaultSkip specifies whether operations are skipped by default.
	// If true, operations are excluded unless x-mcp.skip is explicitly false.
	// If false (default), operations are included unless x-mcp.skip is true.
	DefaultSkip bool `yaml:"default-skip"`
}

type MiddlewareOptions struct {
}

type ModelsPackage struct {
	// Path is the Go import path of the models package. Required.
	Path string `yaml:"path"`

	// Alias is the identifier used to qualify model type references in the
	// generated handler. Defaults to the last path segment of Path.
	Alias string `yaml:"alias,omitempty"`
}

type OperationDefinition struct {
	ID          string
	Summary     string
	Description string
	Method      string
	Path        string
	PathParams  *TypeDefinition
	Header      *RequestParametersDefinition
	Query       *RequestParametersDefinition

	TypeDefinitions []TypeDefinition
	// TODO: check if can be removed
	BodyRequired bool

	Body     *RequestBodyDefinition
	Response ResponseDefinition

	// MCP contains x-mcp extension configuration for MCP tool generation
	MCP *MCPExtension

	// WithResponseTypeName is the name of the envelope wrapper struct emitted
	// when generate.client-with-response is true (e.g. "UploadDocumentResp").
	// Empty when the feature is disabled.
	WithResponseTypeName string

	// StreamMethodName is the streaming sibling's name (e.g. "GetEventsStream"),
	// empty when the feature is off or the operation has no sequential
	// response. Disambiguated via the TypeTracker, because "<ID>Stream"
	// collides readily.
	StreamMethodName string

	// HeaderTypeNames maps each documented status code to the name of the
	// per-status typed header struct emitted alongside the envelope (e.g.
	// 201 -> "UploadDocumentResp201Headers"). Only populated for statuses
	// that declare at least one header in the spec. A range or `default` the
	// envelope used to expose at its stand-in code keeps its old name here,
	// as a deprecated alias; HeaderTypeName returns any response's current name.
	HeaderTypeNames map[int]string
	// contains filtered or unexported fields
}

type Output struct {
	UseSingleFile bool   `yaml:"use-single-file"`
	Directory     string `yaml:"directory"`
	Filename      string `yaml:"filename"`
	SkipFmt       bool   `yaml:"skip-fmt"`
}

type OverlayOptions struct {
	// Sources is a list of overlay files to apply to the OpenAPI spec.
	// Each source can be a file path or URL. Overlays are applied in order.
	Sources []string `yaml:"sources"`
}

type ParameterDefinition struct {
	ParamName string
	In        string
	Required  bool
	Spec      *v3high.Parameter
	Schema    GoSchema
	// contains filtered or unexported fields
}

type ParameterDefinitions []ParameterDefinition

type ParameterEncoding struct {
	Style         string
	Explode       *bool
	Required      bool
	AllowReserved bool
}

type ParseContext struct {
	Operations      []OperationDefinition
	TypeDefinitions map[SpecLocation][]TypeDefinition
	Enums           []EnumDefinition
	UnionTypes      []TypeDefinition
	Imports         []string
	ResponseErrors  []string
	TypeTracker     *TypeTracker
}

type ParseOptions struct {
	OmitDescription        bool
	DefaultIntType         string
	AlwaysPrefixEnumValues bool
	AdditionalTags         []string
	SkipValidation         bool

	// ClientStreaming gates sequential-response detection. Off means no
	// per-frame item types and an empty ResponseDefinition.Streams, so output
	// is bit-for-bit what it was before streaming support existed.
	ClientStreaming bool

	// ClientWithResponse resolves the `default` response next to explicit
	// error codes, which only the envelope client consumes. Off means no type
	// generated for it there, so output is unchanged without the envelope.
	ClientWithResponse bool

	// ErrorMapping maps response type names to the field that should be used
	// for the Error() method. When a response type has error mapping configured,
	// it cannot be an alias (aliases don't support methods).
	ErrorMapping map[string]string
	// contains filtered or unexported fields
}

type Parser struct {
	// contains filtered or unexported fields
}

type Property struct {
	GoName        string
	Description   string
	JsonFieldName string
	Schema        GoSchema
	Extensions    map[string]any
	Deprecated    bool
	Constraints   Constraints
	SensitiveData *runtime.SensitiveDataConfig
	ParentType    string // Name of the parent type (for detecting recursive references)
}

type RequestBodyDefinition struct {
	Name        string
	Required    bool
	Schema      GoSchema
	NameTag     string
	ContentType string
	Default     bool
	Encoding    map[string]RequestBodyEncoding
}

type RequestBodyEncoding struct {
	ContentType string
	Style       string
	Explode     *bool
}

type RequestParametersDefinition struct {
	Name     string
	Encoding map[string]ParameterEncoding
	Params   []ParameterDefinition
	TypeDef  TypeDefinition
}

type ResponseContentDefinition struct {
	Schema      GoSchema
	ContentType string
	NameTag     string

	ResponseName string
	Description  string
	Ref          string
	IsSuccess    bool

	// StatusCode is the documented status code. For a range or `default` it
	// is the stand-in code handler generation uses: 200 for `2XX`, 400 for
	// both `4XX` and `5XX`, 200 or 500 for `default`. The envelope client
	// matches StatusRange and IsDefault instead.
	StatusCode int

	// StatusRange is the class digit of a range such as `4XX` (4), or zero
	// when the response documents an exact status code.
	StatusRange int

	// IsDefault is true for the `default` response.
	IsDefault bool

	Headers map[string]GoSchema
	// IsRaw is true for unsupported content types (XML, form-urlencoded, etc.)
	// that require the user to handle marshaling manually.
	IsRaw bool

	// IsStream is true when the media type the primary method selected is
	// sequential. It does not change the primary method's shape; it lets
	// callers that cannot stream (the MCP tool template) refuse instead of
	// blocking forever.
	IsStream bool
	// contains filtered or unexported fields
}

type ResponseDefinition struct {
	SuccessStatusCode int
	Success           *ResponseContentDefinition
	Error             *ResponseContentDefinition
	All               map[int]*ResponseContentDefinition

	// Successes lists every 2xx response documented under an exact status
	// code, in ascending order. Drives `client-with-response` envelope
	// generation, which needs a deterministic per-status iteration.
	Successes []*ResponseContentDefinition

	// Errors lists every non-2xx response documented under an exact status
	// code, in ascending order. Same motivation as Successes - the envelope
	// populates `JSON404`/`JSON500` fields per documented status.
	Errors []*ResponseContentDefinition

	// StatusRanges lists the responses documented under a range such as
	// `4XX`, in ascending order. The envelope client matches them only after
	// every exact code, so an explicit `404` takes precedence over `4XX`.
	StatusRanges []*ResponseContentDefinition

	// Default is the `default` response, which the envelope client matches
	// last: it covers every status nothing more specific documents. Next to
	// explicit error codes it is only resolved when ParseOptions.ClientWithResponse
	// is set, because nothing else consumes it there.
	Default *ResponseContentDefinition

	// Streams lists every sequential media type documented on a success
	// response, in ascending status order. Populated independently of which
	// media type the primary method selected, so an operation offering both
	// `application/json` and `text/event-stream` appears here without
	// displacing the JSON response.
	Streams []*StreamResponseDefinition
}

type ScaffoldOutput struct {
	// Directory is the output directory, relative to the spec/config file location.
	Directory string `yaml:"directory"`

	// Package is the package name for the generated file.
	Package string `yaml:"package"`

	// Overwrite forces regeneration of scaffold-once files (e.g., service.go, middleware.go).
	// Normally these files are only generated if they don't exist. Defaults to false.
	Overwrite bool `yaml:"overwrite"`
}

type SchemaDescriptor struct {
	Fields                   []FieldDescriptor
	HasAdditionalProperties  bool
	AdditionalPropertiesType string
}

type ServerOptions struct {
	// Directory is the output directory for server/main.go.
	// Defaults to "server".
	Directory string `yaml:"directory"`

	// Port is the port the server listens on. Defaults to 8080.
	Port int `yaml:"port"`

	// Timeout is the request timeout in seconds. Defaults to 30.
	Timeout int `yaml:"timeout"`

	// HandlerPackage is the full import path of the handler package.
	// Required when server generation is enabled.
	HandlerPackage string `yaml:"handler-package"`
}

type ServiceOptions struct {
}

type SpecLocation string

type StreamResponseDefinition struct {
	StatusCode  int
	ContentType string
	// Framing is "sse" or "lines".
	Framing string
	// ItemName is the Go type of one frame, e.g. "Event", or "[]byte" when
	// there is no per-item schema that can be JSON-decoded.
	ItemName string
}

type TplOperationsContext struct {
	Operations    []OperationDefinition
	Imports       []string
	Config        Configuration
	WithHeader    bool
	ServerOptions *ServerOptions
	PackageName   string

	// ErrorConstructors holds the error types that have a generated New<Type>(message string) constructor.
	ErrorConstructors map[string]bool
}

type TplTypeContext struct {
	Types []TypeDefinition

	// Map of type names to schemas for cross-referencing
	TypeSchemaMap  map[string]GoSchema
	Imports        []string
	SpecLocation   string
	Config         Configuration
	WithHeader     bool
	ResponseErrors map[string]bool
	TypeTracker    *TypeTracker
}

type TypeDefinition struct {
	Name             string
	JsonName         string
	Schema           GoSchema
	SpecLocation     SpecLocation
	NeedsMarshaler   bool
	HasSensitiveData bool
}

type TypeTracker struct {
	// contains filtered or unexported fields
}

type UnionElement struct {
	// TypeName is the Go type name (e.g., "User", "string", "int")
	TypeName string

	// Schema contains the full schema including constraints (minLength, minimum, etc.)
	Schema GoSchema
}

type ValidationOptions struct {
	// Skip specifies whether to skip Validation method generation. Defaults to false.
	Skip bool `yaml:"skip"`

	// Simple specifies whether to use the simple validation approach. Defaults to false.
	// Simple validation uses validate.Struct() for all types, whereas complex validation generates custom Validate() methods.
	Simple bool `yaml:"simple"`

	// Response specifies whether to generate Validate() methods for response types.
	// Useful for contract testing to ensure responses match the OpenAPI spec. Defaults to false.
	Response bool `yaml:"response"`
}