differ

type BreakingChangeRule struct {
	// Severity overrides the default severity for this change type.
	// If nil, the default severity is used.
	Severity *Severity

	// Ignore completely ignores this change type (not included in results).
	Ignore bool
}

type BreakingRulesConfig struct {
	// Operation configures rules for operation-level changes
	Operation *OperationRules

	// Parameter configures rules for parameter changes
	Parameter *ParameterRules

	// RequestBody configures rules for request body changes
	RequestBody *RequestBodyRules

	// Response configures rules for response changes
	Response *ResponseRules

	// Schema configures rules for schema changes
	Schema *SchemaRules

	// Security configures rules for security scheme changes
	Security *SecurityRules

	// Server configures rules for server changes
	Server *ServerRules

	// Endpoint configures rules for endpoint (path) changes
	Endpoint *EndpointRules

	// Info configures rules for info object changes
	Info *InfoRules

	// Extension configures rules for extension (x-*) changes
	Extension *ExtensionRules
}

type Change struct {
	// Path is the JSON path to the changed element (e.g., "paths./pets.get")
	Path string
	// Type indicates if this is an addition, removal, or modification
	Type ChangeType
	// Category indicates which part of the spec was changed
	Category ChangeCategory
	// Severity indicates the impact level (only used in ModeBreaking)
	Severity Severity
	// OldValue is the value in the source document (nil for additions)
	OldValue any
	// NewValue is the value in the target document (nil for removals)
	NewValue any
	// Message is a human-readable description of the change
	Message string
	// Line is the 1-based line number in the source file (0 if unknown)
	Line int
	// Column is the 1-based column number in the source file (0 if unknown)
	Column int
	// File is the source file path (empty for main document)
	File string
}

type ChangeCategory string

type ChangeType string

type DiffMode int

type DiffResult struct {
	// SourceVersion is the source document's OAS version string
	SourceVersion string
	// SourceOASVersion is the enumerated source OAS version
	SourceOASVersion parser.OASVersion
	// SourceStats contains statistical information about the source document
	SourceStats parser.DocumentStats
	// SourceSize is the size of the source document in bytes
	SourceSize int64
	// TargetVersion is the target document's OAS version string
	TargetVersion string
	// TargetOASVersion is the enumerated target OAS version
	TargetOASVersion parser.OASVersion
	// TargetStats contains statistical information about the target document
	TargetStats parser.DocumentStats
	// TargetSize is the size of the target document in bytes
	TargetSize int64
	// TargetDocument contains the target/right document for ToParseResult() chaining.
	// In a pipeline model, returning the target enables workflows like:
	// diff(v1, v2) → validate(v2) → publish
	TargetDocument any
	// TargetSourcePath is the target document's source path
	TargetSourcePath string
	// TargetSourceFormat is the target document's format (JSON or YAML)
	TargetSourceFormat parser.SourceFormat
	// Changes contains all detected changes
	Changes []Change
	// BreakingCount is the number of breaking changes (Critical + Error severity)
	BreakingCount int
	// WarningCount is the number of warnings
	WarningCount int
	// InfoCount is the number of informational changes
	InfoCount int
	// HasBreakingChanges is true if any breaking changes were detected
	HasBreakingChanges bool
}

type Differ struct {
	// Mode determines the type of diff operation (Simple or Breaking)
	Mode DiffMode
	// IncludeInfo determines whether to include informational changes
	IncludeInfo bool
	// UserAgent is the User-Agent string used when fetching URLs
	// Defaults to "oastools" if not set
	UserAgent string
	// SourceMap provides source location lookup for the source document.
	// When set, changes will include Line, Column, and File information
	// for elements in the source document.
	SourceMap *parser.SourceMap
	// TargetMap provides source location lookup for the target document.
	// When set, changes will include Line, Column, and File information
	// for elements in the target document (used for additions).
	TargetMap *parser.SourceMap
	// BreakingRules configures which changes are considered breaking
	// and their severity levels. When nil, default rules are used.
	// See BreakingRulesConfig for configuration options.
	BreakingRules *BreakingRulesConfig
}

type EndpointRules struct {
	// Removed configures the rule for when an endpoint is removed.
	// Default: SeverityCritical
	Removed *BreakingChangeRule

	// Added configures the rule for when an endpoint is added.
	// Default: SeverityInfo
	Added *BreakingChangeRule

	// DescriptionModified configures the rule for description changes.
	// Default: SeverityInfo
	DescriptionModified *BreakingChangeRule
}

type ExtensionRules struct {
	// Removed configures the rule for when an extension is removed.
	// Default: SeverityInfo
	Removed *BreakingChangeRule

	// Added configures the rule for when an extension is added.
	// Default: SeverityInfo
	Added *BreakingChangeRule

	// Modified configures the rule for when an extension is modified.
	// Default: SeverityInfo
	Modified *BreakingChangeRule
}

type InfoRules struct {
	// TitleModified configures the rule for title changes.
	// Default: SeverityInfo
	TitleModified *BreakingChangeRule

	// VersionModified configures the rule for version changes.
	// Default: SeverityInfo
	VersionModified *BreakingChangeRule

	// DescriptionModified configures the rule for description changes.
	// Default: SeverityInfo
	DescriptionModified *BreakingChangeRule
}

type OperationRules struct {
	// Removed configures the rule for when an operation is removed.
	// Default: SeverityCritical
	Removed *BreakingChangeRule

	// OperationIDModified configures the rule for operationId changes.
	// Default: SeverityWarning
	OperationIDModified *BreakingChangeRule

	// SummaryModified configures the rule for summary changes.
	// Default: SeverityInfo
	SummaryModified *BreakingChangeRule

	// DescriptionModified configures the rule for description changes.
	// Default: SeverityInfo
	DescriptionModified *BreakingChangeRule

	// DeprecatedModified configures the rule for deprecated flag changes.
	// Default: SeverityInfo
	DeprecatedModified *BreakingChangeRule

	// TagsModified configures the rule for operation tags changes.
	// Default: SeverityInfo
	TagsModified *BreakingChangeRule

	// Added configures the rule for when an operation is added.
	// Default: SeverityInfo
	Added *BreakingChangeRule
}

type Option func(*diffConfig) error

type ParameterRules struct {
	// Removed configures the rule for when a parameter is removed.
	// Default: SeverityError (required) / SeverityWarning (optional)
	Removed *BreakingChangeRule

	// Added configures the rule for when a parameter is added.
	// Default: SeverityError (required) / SeverityInfo (optional)
	Added *BreakingChangeRule

	// RequiredChanged configures the rule for required field changes.
	// Default: SeverityError (false→true) / SeverityInfo (true→false)
	RequiredChanged *BreakingChangeRule

	// TypeChanged configures the rule for type changes.
	// Default: SeverityError
	TypeChanged *BreakingChangeRule

	// FormatChanged configures the rule for format changes.
	// Default: SeverityWarning
	FormatChanged *BreakingChangeRule

	// StyleChanged configures the rule for style changes.
	// Default: SeverityWarning
	StyleChanged *BreakingChangeRule

	// SchemaChanged configures the rule for schema changes.
	// Default: varies by schema change
	SchemaChanged *BreakingChangeRule

	// DescriptionModified configures the rule for description changes.
	// Default: SeverityInfo
	DescriptionModified *BreakingChangeRule
}

type RequestBodyRules struct {
	// Removed configures the rule for when a request body is removed.
	// Default: SeverityError
	Removed *BreakingChangeRule

	// Added configures the rule for when a request body is added.
	// Default: SeverityError (required) / SeverityInfo (optional)
	Added *BreakingChangeRule

	// RequiredChanged configures the rule for required field changes.
	// Default: SeverityError (false→true) / SeverityInfo (true→false)
	RequiredChanged *BreakingChangeRule

	// MediaTypeRemoved configures the rule for when a media type is removed.
	// Default: SeverityWarning
	MediaTypeRemoved *BreakingChangeRule

	// MediaTypeAdded configures the rule for when a media type is added.
	// Default: SeverityInfo
	MediaTypeAdded *BreakingChangeRule

	// SchemaChanged configures the rule for schema changes.
	// Default: varies by schema change
	SchemaChanged *BreakingChangeRule
}

type ResponseRules struct {
	// Removed configures the rule for when a response is removed.
	// Default: SeverityError (success codes) / SeverityWarning (error codes)
	Removed *BreakingChangeRule

	// Added configures the rule for when a response is added.
	// Default: SeverityInfo
	Added *BreakingChangeRule

	// DescriptionModified configures the rule for description changes.
	// Default: SeverityInfo
	DescriptionModified *BreakingChangeRule

	// MediaTypeRemoved configures the rule for when a media type is removed.
	// Default: SeverityWarning
	MediaTypeRemoved *BreakingChangeRule

	// MediaTypeAdded configures the rule for when a media type is added.
	// Default: SeverityInfo
	MediaTypeAdded *BreakingChangeRule

	// HeaderRemoved configures the rule for when a header is removed.
	// Default: SeverityWarning
	HeaderRemoved *BreakingChangeRule

	// HeaderAdded configures the rule for when a header is added.
	// Default: SeverityInfo
	HeaderAdded *BreakingChangeRule

	// SchemaChanged configures the rule for schema changes.
	// Default: varies by schema change
	SchemaChanged *BreakingChangeRule
}

type RuleKey struct {
	Category   ChangeCategory
	ChangeType ChangeType
	SubType    string // Additional context (e.g., "operationId", "required")
}

type SchemaRules struct {
	// Removed configures the rule for when a schema is removed.
	// Default: SeverityError
	Removed *BreakingChangeRule

	// Added configures the rule for when a schema is added.
	// Default: SeverityInfo
	Added *BreakingChangeRule

	// TypeChanged configures the rule for type changes.
	// Default: SeverityError
	TypeChanged *BreakingChangeRule

	// FormatChanged configures the rule for format changes.
	// Default: SeverityWarning
	FormatChanged *BreakingChangeRule

	// RequiredAdded configures the rule for when a required field is added.
	// Default: SeverityError
	RequiredAdded *BreakingChangeRule

	// RequiredRemoved configures the rule for when a required field is removed.
	// Default: SeverityInfo
	RequiredRemoved *BreakingChangeRule

	// PropertyRemoved configures the rule for when a property is removed.
	// Default: SeverityWarning
	PropertyRemoved *BreakingChangeRule

	// PropertyAdded configures the rule for when a property is added.
	// Default: SeverityInfo
	PropertyAdded *BreakingChangeRule

	// EnumValueRemoved configures the rule for when an enum value is removed.
	// Default: SeverityError
	EnumValueRemoved *BreakingChangeRule

	// EnumValueAdded configures the rule for when an enum value is added.
	// Default: SeverityInfo
	EnumValueAdded *BreakingChangeRule

	// MaximumDecreased configures the rule for when maximum is decreased.
	// Default: SeverityError
	MaximumDecreased *BreakingChangeRule

	// MinimumIncreased configures the rule for when minimum is increased.
	// Default: SeverityError
	MinimumIncreased *BreakingChangeRule

	// MaxLengthDecreased configures the rule for when maxLength is decreased.
	// Default: SeverityError
	MaxLengthDecreased *BreakingChangeRule

	// MinLengthIncreased configures the rule for when minLength is increased.
	// Default: SeverityWarning
	MinLengthIncreased *BreakingChangeRule

	// PatternChanged configures the rule for when pattern is changed.
	// Default: SeverityWarning
	PatternChanged *BreakingChangeRule

	// NullableRemoved configures the rule for when nullable is removed.
	// Default: SeverityError
	NullableRemoved *BreakingChangeRule

	// NullableAdded configures the rule for when nullable is added.
	// Default: SeverityInfo
	NullableAdded *BreakingChangeRule

	// AdditionalPropertiesChanged configures the rule for additionalProperties changes.
	// Default: SeverityWarning
	AdditionalPropertiesChanged *BreakingChangeRule

	// DescriptionModified configures the rule for description changes.
	// Default: SeverityInfo
	DescriptionModified *BreakingChangeRule
}

type SecurityRules struct {
	// Removed configures the rule for when a security scheme is removed.
	// Default: SeverityError
	Removed *BreakingChangeRule

	// Added configures the rule for when a security scheme is added.
	// Default: SeverityWarning
	Added *BreakingChangeRule

	// TypeChanged configures the rule for type changes.
	// Default: SeverityError
	TypeChanged *BreakingChangeRule

	// ScopeRemoved configures the rule for when a scope is removed.
	// Default: SeverityWarning
	ScopeRemoved *BreakingChangeRule

	// ScopeAdded configures the rule for when a scope is added.
	// Default: SeverityInfo
	ScopeAdded *BreakingChangeRule
}

type ServerRules struct {
	// Removed configures the rule for when a server is removed.
	// Default: SeverityWarning
	Removed *BreakingChangeRule

	// Added configures the rule for when a server is added.
	// Default: SeverityInfo
	Added *BreakingChangeRule

	// DescriptionModified configures the rule for description changes.
	// Default: SeverityInfo
	DescriptionModified *BreakingChangeRule

	// VariableChanged configures the rule for server variable changes.
	// Default: SeverityWarning
	VariableChanged *BreakingChangeRule
}

type Severity = severity.Severity