converter

type ExtendsEntry struct {
	Name     string // e.g., "spectral:oas", "speakeasy-recommended"
	Modifier string // e.g., "all", "recommended", "off" (empty if not specified)
}

type GenerateOption func(*GenerateOptions)

type GenerateOptions struct {
	// RulesDir is the relative path for .ts files in config (default "./rules").
	RulesDir string

	// RulePrefix is the prefix for generated rule IDs (default "custom-").
	RulePrefix string
}

type GenerateResult struct {
	// Config is the native lint config, serializable to YAML.
	Config *linter.Config

	// GeneratedRules maps ruleID -> TypeScript source code.
	GeneratedRules map[string]string

	// Warnings from the generation phase.
	Warnings []Warning
	// contains filtered or unexported fields
}

type IntermediateConfig struct {
	// Extends stores the raw extends values from the source config.
	// Examples: ["spectral:oas"], ["speakeasy-recommended"]
	// Interpretation of these values is left to the consumer (Generate maps them).
	Extends []ExtendsEntry

	// Rules is the unified list of all rules from the source config.
	// Each rule is either a severity-only override or a full rule definition.
	// Parse does NOT classify rules as "builtin" vs "custom" — that's a
	// consumer concern. Rules with Given/Then populated are custom rules;
	// rules with only Severity set are overrides.
	Rules []Rule

	// Warnings collected during parsing (malformed entries, etc.)
	Warnings []Warning
}

type JSONPathMapping struct {
	// Collection is the index collection name (e.g., "operations", "inlinePathItems").
	// Empty for direct document access patterns.
	Collection string

	// IsKeyAccess is true when the ~ operator is used (extract map key).
	IsKeyAccess bool

	// FieldAccess is a field to extract from each node (e.g., "url" for $.servers[*].url).
	FieldAccess string

	// Filter is a filter expression stripped during structural matching,
	// to be re-applied as generated TypeScript.
	Filter string

	// HTTPMethod is set when matching $.paths[*].{method} patterns.
	HTTPMethod string

	// IsDirect is true when the path targets a single document location
	// (e.g., $.info, $.components) rather than an indexed collection.
	IsDirect bool

	// DirectAccess is the TypeScript expression for direct access.
	DirectAccess string

	// Unsupported is true when the JSONPath could not be mapped.
	Unsupported bool

	// OriginalPath is the original JSONPath expression.
	OriginalPath string
}

type Rule struct {
	ID          string      // rule name/ID from source config
	Description string      // rule description
	Message     string      // message template with {{placeholders}}
	Severity    string      // normalized severity (see doc comment above)
	Resolved    *bool       // nil = default (resolved), false = unresolved
	Formats     []string    // "oas2", "oas3", "oas3.0", "oas3.1"
	Source      string      // ruleset name this rule came from (for dedup tracing)
	Given       []string    // JSONPath expressions (empty for overrides)
	Then        []RuleCheck // checks to apply (empty for overrides)
}

type RuleCheck struct {
	Field           string         // field to check (empty = check the node itself)
	Function        string         // "truthy", "pattern", "enumeration", etc.
	FunctionOptions map[string]any // function-specific options (documented above)
	Message         string         // per-check message override
}

type Warning struct {
	RuleID  string // the rule this warning relates to (empty for global warnings)
	Phase   string // "parse" or "generate"
	Message string
}