types

type APIStyleSpec struct {
	// Schema is the JSON Schema URI for validation.
	Schema string `json:"$schema,omitempty"`

	// Version is the semantic version of this specification.
	Version string `json:"version"`

	// Name is a unique identifier for this style spec.
	Name string `json:"name"`

	// Description provides context about this style specification.
	Description string `json:"description,omitempty"`

	// Introduction provides detailed introductory content (Markdown).
	Introduction string `json:"introduction,omitempty"`

	// Extends lists parent profiles to inherit rules from.
	Extends []string `json:"extends,omitempty"`

	// Rules are the style rules defined in this specification.
	Rules []Rule `json:"rules"`

	// Overrides modify inherited rules from extended profiles.
	Overrides map[string]RuleOverride `json:"overrides,omitempty"`

	// Lexicon defines approved and forbidden terminology.
	Lexicon *Lexicon `json:"lexicon,omitempty"`

	// ConformanceLevels define graduated compliance tiers.
	ConformanceLevels map[string]ConformanceLevel `json:"conformanceLevels,omitempty"`

	// Exceptions are approved rule waivers.
	Exceptions []Exception `json:"exceptions,omitempty"`

	// Categories defines available rule categories with metadata.
	Categories []Category `json:"categories,omitempty"`

	// Patterns defines reusable API design patterns.
	Patterns []Pattern `json:"patterns,omitempty"`

	// Sections defines document structure for navigation.
	Sections []Section `json:"sections,omitempty"`

	// Glossary defines terminology used in the specification.
	Glossary []GlossaryTerm `json:"glossary,omitempty"`

	// Principles defines high-level design principles.
	Principles []Principle `json:"principles,omitempty"`

	// Metadata contains additional specification information.
	Metadata *SpecMetadata `json:"metadata,omitempty"`
}

type CasingRules struct {
	// Paths defines casing for URL paths (e.g., "kebab-case").
	Paths string `json:"paths,omitempty"`
	// Parameters defines casing for query/path parameters.
	Parameters string `json:"parameters,omitempty"`
	// Properties defines casing for JSON properties.
	Properties string `json:"properties,omitempty"`
	// Headers defines casing for HTTP headers.
	Headers string `json:"headers,omitempty"`
}

type Category struct {
	// ID is the category identifier (e.g., "uri-design").
	ID string `json:"id"`
	// Title is the display name.
	Title string `json:"title"`
	// Description explains what this category covers.
	Description string `json:"description,omitempty"`
	// Order determines display ordering (lower = first).
	Order int `json:"order,omitempty"`
}

type CodeAnnotation struct {
	// Line is the starting line number (1-indexed).
	Line int `json:"line"`

	// EndLine is the ending line number (optional, for multi-line annotations).
	EndLine int `json:"endLine,omitempty"`

	// Text is the annotation message.
	Text string `json:"text"`

	// Type indicates the annotation severity or purpose.
	Type string `json:"type,omitempty"` // "info", "warning", "error"
}

type Condition struct {
	// When is a natural language description of when this condition applies.
	When string `json:"when"`

	// Expression is a JSONPath or CEL expression for evaluation.
	Expression string `json:"expression,omitempty"`

	// Then describes what should happen when the condition is met.
	Then string `json:"then"`

	// Unless describes exceptions to the condition.
	Unless string `json:"unless,omitempty"`
}

type ConformanceLevel struct {
	// Description explains what this level represents.
	Description string `json:"description,omitempty"`

	// RequiredCategories lists category IDs that must pass.
	RequiredCategories []string `json:"requiredCategories,omitempty"`

	// RequiredRules lists specific rule IDs that must pass.
	RequiredRules []string `json:"requiredRules,omitempty"`

	// MaxErrors is the maximum allowed error-severity violations.
	MaxErrors int `json:"maxErrors"`

	// MaxWarnings is the maximum allowed warning-severity violations.
	MaxWarnings int `json:"maxWarnings"`

	// Extends inherits requirements from another level.
	Extends string `json:"extends,omitempty"`
}

type DecisionRow struct {
	// Values are the cell values in order.
	Values []string `json:"values"`

	// Highlight indicates if this row should be emphasized.
	Highlight bool `json:"highlight,omitempty"`
}

type DecisionTable struct {
	// Title is the table title.
	Title string `json:"title"`

	// Description explains the table's purpose.
	Description string `json:"description,omitempty"`

	// Headers are the column headers.
	Headers []string `json:"headers"`

	// Rows are the table data rows.
	Rows []DecisionRow `json:"rows"`
}

type DeprecationInfo struct {
	// Version is when the rule was deprecated.
	Version string `json:"version"`

	// Message explains why the rule is deprecated.
	Message string `json:"message"`

	// ReplacedBy lists rule IDs that replace this rule.
	ReplacedBy []string `json:"replacedBy,omitempty"`

	// RemovalVersion indicates when the rule will be removed.
	RemovalVersion string `json:"removalVersion,omitempty"`
}

type DetailedExample struct {
	// Title is a brief description of the example.
	Title string `json:"title"`

	// Description provides additional context for the example.
	Description string `json:"description,omitempty"`

	// Type indicates whether this is a good, bad, or context example.
	Type string `json:"type"` // "good", "bad", "context"

	// Language specifies the code language (e.g., "openapi", "json", "http").
	Language string `json:"language,omitempty"`

	// Code is the example code or content.
	Code string `json:"code"`

	// Annotations highlight specific parts of the code.
	Annotations []CodeAnnotation `json:"annotations,omitempty"`

	// Before shows the state before migration (for migration examples).
	Before string `json:"before,omitempty"`

	// After shows the state after migration (for migration examples).
	After string `json:"after,omitempty"`
}

type Diagram struct {
	// Title is the diagram title.
	Title string `json:"title"`

	// Type specifies the diagram format.
	Type string `json:"type"` // "mermaid", "plantuml", "url"

	// Content is the diagram content (code for mermaid/plantuml, URL for url type).
	Content string `json:"content"`

	// Alt is alternative text for accessibility.
	Alt string `json:"alt,omitempty"`
}

type Enforcement struct {
	// Type is the enforcement mechanism.
	Type EnforcementType `json:"type"`

	// Function is the Spectral function name (for type=spectral).
	Function string `json:"function,omitempty"`

	// Options are function-specific configuration options.
	Options *EnforcementOptions `json:"options,omitempty"`

	// Given is the JSONPath expression(s) for targeting nodes (Spectral-style).
	// Can be a single string or array of strings.
	Given *GivenPaths `json:"given,omitempty"`

	// Then defines the assertion to apply (Spectral-style).
	Then *SpectralThen `json:"then,omitempty"`

	// Pattern is the regex pattern (for type=regex).
	Pattern string `json:"pattern,omitempty"`

	// CustomFunction is the name of a custom Go function (for type=custom).
	CustomFunction string `json:"customFunction,omitempty"`
}

type EnforcementOptions struct {
	// Match is a regex pattern to match against (for pattern function).
	Match string `json:"match,omitempty"`
	// NotMatch is a regex pattern that should not match.
	NotMatch string `json:"notMatch,omitempty"`
	// Min is a minimum value (for length function).
	Min *int `json:"min,omitempty"`
	// Max is a maximum value (for length function).
	Max *int `json:"max,omitempty"`
	// Values is a list of allowed values (for enumeration function).
	Values []string `json:"values,omitempty"`
	// Type specifies the expected casing type (for casing function).
	// Values: flat, camel, pascal, kebab, cobol, snake, macro
	Type string `json:"type,omitempty"`
	// Separator is used for casing validation.
	Separator string `json:"separator,omitempty"`
	// Schema is a JSON Schema for validation (for schema function).
	Schema string `json:"schema,omitempty"`
}

type EnforcementType string

type Examples struct {
	// Good shows correct usage patterns.
	Good []string `json:"good,omitempty"`
	// Bad shows incorrect usage patterns.
	Bad []string `json:"bad,omitempty"`
	// Detailed provides rich examples with annotations and context.
	Detailed []DetailedExample `json:"detailed,omitempty"`
}

type Exception struct {
	// ID is a unique identifier for this exception.
	ID string `json:"id"`

	// RuleID is the rule being waived.
	RuleID string `json:"ruleId"`

	// AppliesTo defines the scope of the exception.
	AppliesTo *ExceptionScope `json:"appliesTo,omitempty"`

	// Reason explains why this exception was granted.
	Reason string `json:"reason"`

	// ApprovedBy identifies who approved the exception.
	ApprovedBy string `json:"approvedBy,omitempty"`

	// ApprovedOn is when the exception was granted.
	ApprovedOn *time.Time `json:"approvedOn,omitempty"`

	// ExpiresOn is when the exception expires (nil = never).
	ExpiresOn *time.Time `json:"expiresOn,omitempty"`

	// Ticket links to an issue tracker for tracking.
	Ticket string `json:"ticket,omitempty"`
}

type ExceptionScope struct {
	// API limits the exception to a specific API name.
	API string `json:"api,omitempty"`
	// Path limits the exception to specific paths (glob supported).
	Path string `json:"path,omitempty"`
	// Operation limits the exception to specific operations.
	Operation string `json:"operation,omitempty"`
	// Paths lists multiple paths (alternative to single Path).
	Paths []string `json:"paths,omitempty"`
}

type FileLintReport struct {
	// File is the path to the linted specification.
	File string `json:"file"`

	// Report contains the lint results for this file.
	*LintReport
}

type ForbiddenTerm struct {
	// Term is the forbidden word or phrase.
	Term string `json:"term"`
	// ReplaceWith suggests the preferred alternative.
	ReplaceWith string `json:"replaceWith,omitempty"`
	// Reason explains why this term is forbidden.
	Reason string `json:"reason,omitempty"`
}

type GivenPaths struct {
	// Paths contains one or more JSONPath expressions.
	Paths []string `json:"paths"`
}

type GlossaryTerm struct {
	// Term is the word or phrase being defined.
	Term string `json:"term"`

	// Definition explains the term.
	Definition string `json:"definition"`

	// Aliases are alternative names for the term.
	Aliases []string `json:"aliases,omitempty"`
}

type JudgeCriteria struct {
	// Prompt is the evaluation instruction for the LLM.
	Prompt string `json:"prompt"`

	// Weight influences scoring (0.0-1.0, default 1.0).
	Weight float64 `json:"weight,omitempty"`

	// RequiresContext indicates if broader context is needed for evaluation.
	RequiresContext bool `json:"requiresContext,omitempty"`

	// Category overrides the rule's category for evaluation grouping.
	Category string `json:"category,omitempty"`

	// PassCriteria lists requirements for a "pass" score.
	PassCriteria []string `json:"passCriteria,omitempty"`

	// PartialCriteria lists requirements for a "partial" score.
	PartialCriteria []string `json:"partialCriteria,omitempty"`

	// FailCriteria lists requirements for a "fail" score.
	FailCriteria []string `json:"failCriteria,omitempty"`

	// Examples provides few-shot examples for LLM evaluation.
	Examples *JudgeExamples `json:"examples,omitempty"`

	// ScaleType defines the scoring scale type.
	ScaleType string `json:"scaleType,omitempty"` // "categorical", "binary", "checklist"
}

type JudgeExample struct {
	// Excerpt is the example API content or snippet.
	Excerpt string `json:"excerpt"`
	// Reasoning explains why this example gets this score (chain-of-thought).
	Reasoning string `json:"reasoning"`
}

type JudgeExamples struct {
	// Pass is an example that demonstrates passing.
	Pass *JudgeExample `json:"pass,omitempty"`
	// Partial is an example that demonstrates partial compliance.
	Partial *JudgeExample `json:"partial,omitempty"`
	// Fail is an example that demonstrates failure.
	Fail *JudgeExample `json:"fail,omitempty"`
}

type Lexicon struct {
	// Approved lists terms that should be used.
	Approved []string `json:"approved,omitempty"`

	// Forbidden lists terms that should not be used, with replacements.
	Forbidden []ForbiddenTerm `json:"forbidden,omitempty"`

	// Aliases maps equivalent terms.
	Aliases map[string]string `json:"aliases,omitempty"`

	// CasingRules defines naming conventions for different contexts.
	CasingRules *CasingRules `json:"casingRules,omitempty"`
}

type LintReport struct {
	// Status is the overall pass/fail result.
	Status ReportStatus `json:"status"`

	// ConformanceLevel is the highest level achieved (if levels are defined).
	ConformanceLevel string `json:"conformanceLevel,omitempty"`

	// Summary provides violation counts by severity.
	Summary *ViolationSummary `json:"summary"`

	// Violations lists all findings.
	Violations []Violation `json:"violations"`

	// IgnoredViolations lists violations that were suppressed by exceptions.
	IgnoredViolations []Violation `json:"ignoredViolations,omitempty"`

	// Metadata includes timing, versions, and other context.
	Metadata *ReportMetadata `json:"metadata,omitempty"`
}

type MigrationGuidance struct {
	// Summary is a brief description of the migration.
	Summary string `json:"summary"`

	// Steps are ordered migration steps.
	Steps []MigrationStep `json:"steps,omitempty"`

	// AutoFixAvailable indicates if an automated fix is available.
	AutoFixAvailable bool `json:"autoFixAvailable,omitempty"`

	// Effort estimates the work required.
	Effort string `json:"effort,omitempty"` // "low", "medium", "high"

	// BreakingChange indicates if this migration is a breaking change.
	BreakingChange bool `json:"breakingChange,omitempty"`
}

type MigrationStep struct {
	// Order is the step sequence number.
	Order int `json:"order"`

	// Description explains what to do in this step.
	Description string `json:"description"`

	// Code provides example code for the step.
	Code string `json:"code,omitempty"`

	// Language specifies the code language.
	Language string `json:"language,omitempty"`
}

type MultiLintReport struct {
	// Status is the overall pass/fail result across all files.
	Status Status `json:"status"`

	// Summary provides aggregate violation counts across all files.
	Summary *ViolationSummary `json:"summary"`

	// FileReports contains individual reports for each file.
	FileReports []FileLintReport `json:"fileReports"`

	// Metadata includes timing, versions, and other context.
	Metadata *ReportMetadata `json:"metadata,omitempty"`
}

type Pattern struct {
	// ID is a unique identifier for the pattern.
	ID string `json:"id"`

	// Name is the human-readable name.
	Name string `json:"name"`

	// Category groups related patterns (e.g., "collections", "errors", "versioning").
	Category string `json:"category,omitempty"`

	// Summary is a brief one-line description.
	Summary string `json:"summary"`

	// Description provides extended prose explanation (Markdown).
	Description string `json:"description,omitempty"`

	// Problem describes what issue this pattern addresses.
	Problem string `json:"problem,omitempty"`

	// Solution describes how the pattern solves the problem.
	Solution string `json:"solution,omitempty"`

	// When describes when to use this pattern.
	When string `json:"when,omitempty"`

	// Examples provides detailed usage examples.
	Examples []DetailedExample `json:"examples,omitempty"`

	// RelatedRules lists rule IDs that implement or relate to this pattern.
	RelatedRules []string `json:"relatedRules,omitempty"`

	// RelatedPatterns lists other pattern IDs that work with this one.
	RelatedPatterns []string `json:"relatedPatterns,omitempty"`

	// References links to external documentation.
	References []Reference `json:"references,omitempty"`

	// Diagrams provides visual representations of the pattern.
	Diagrams []Diagram `json:"diagrams,omitempty"`
}

type Principle struct {
	// ID is a unique identifier for the principle.
	ID string `json:"id"`

	// Title is the principle name.
	Title string `json:"title"`

	// Description explains the principle in detail (Markdown).
	Description string `json:"description"`

	// RelatedRules lists rule IDs that implement this principle.
	RelatedRules []string `json:"relatedRules,omitempty"`
}

type Reference struct {
	// Title is the display text for the reference.
	Title string `json:"title"`
	// URL is the link to the external resource.
	URL string `json:"url"`
}

type ReportMetadata struct {
	// SpecFile is the path to the linted specification.
	SpecFile string `json:"specFile,omitempty"`

	// SpecVersion is the OpenAPI version of the spec.
	SpecVersion string `json:"specVersion,omitempty"`

	// Profile is the style profile used.
	Profile string `json:"profile,omitempty"`

	// ProfileVersion is the version of the profile.
	ProfileVersion string `json:"profileVersion,omitempty"`

	// Duration is how long linting took.
	Duration time.Duration `json:"duration,omitempty"`

	// DurationMS is duration in milliseconds (for JSON serialization).
	DurationMS int64 `json:"durationMs,omitempty"`

	// Timestamp is when linting was performed.
	Timestamp time.Time `json:"timestamp"`

	// ToolVersion is the api-style-spec version.
	ToolVersion string `json:"toolVersion,omitempty"`

	// RulesEvaluated is the count of rules that were checked.
	RulesEvaluated int `json:"rulesEvaluated,omitempty"`
}

type ReportStatus = Status

type Rule struct {
	// ID is a unique identifier for the rule (e.g., "URI-001").
	ID string `json:"id"`

	// Title is a short, descriptive name for the rule.
	Title string `json:"title"`

	// Category groups related rules (e.g., "uri-design", "naming", "security").
	Category string `json:"category"`

	// Severity indicates the importance of violations.
	Severity Severity `json:"severity"`

	// Scope defines what part of the spec this rule applies to.
	Scope Scope `json:"scope,omitempty"`

	// Rationale explains why this rule exists and its benefits.
	Rationale string `json:"rationale,omitempty"`

	// Description provides extended prose explanation (Markdown).
	Description string `json:"description,omitempty"`

	// Background provides historical or industry context.
	Background string `json:"background,omitempty"`

	// SectionRef links to a document section ID.
	SectionRef string `json:"sectionRef,omitempty"`

	// Priority determines ordering within category (lower = higher priority).
	Priority int `json:"priority,omitempty"`

	// Version indicates when this rule was added or last changed.
	Version string `json:"version,omitempty"`

	// Deprecated provides deprecation information if the rule is deprecated.
	Deprecated *DeprecationInfo `json:"deprecated,omitempty"`

	// Examples provides good and bad usage patterns.
	Examples *Examples `json:"examples,omitempty"`

	// Enforcement defines deterministic checking configuration.
	Enforcement *Enforcement `json:"enforcement,omitempty"`

	// Judge defines LLM evaluation criteria for this rule.
	Judge *JudgeCriteria `json:"judge,omitempty"`

	// References links to external documentation.
	References []Reference `json:"references,omitempty"`

	// Tags are labels for filtering and grouping rules.
	Tags []string `json:"tags,omitempty"`

	// Recommended indicates if this rule is part of the recommended set.
	Recommended bool `json:"recommended,omitempty"`

	// Applicability defines when this rule applies.
	Applicability *RuleApplicability `json:"applicability,omitempty"`

	// Conditions are if/then/unless logic for rule application.
	Conditions []Condition `json:"conditions,omitempty"`

	// Relations define dependencies on other rules.
	Relations []RuleRelation `json:"relations,omitempty"`

	// DecisionTables provide structured decision guidance.
	DecisionTables []DecisionTable `json:"decisionTables,omitempty"`

	// Migration provides guidance for fixing violations.
	Migration *MigrationGuidance `json:"migration,omitempty"`
}

type RuleApplicability struct {
	// APITypes specifies which API types this rule applies to.
	APITypes []string `json:"apiTypes,omitempty"` // "rest", "graphql", "grpc"

	// OpenAPIVersions specifies which OpenAPI versions this rule applies to.
	OpenAPIVersions []string `json:"openAPIVersions,omitempty"` // "3.0", "3.1"

	// HTTPMethods specifies which HTTP methods this rule applies to.
	HTTPMethods []string `json:"httpMethods,omitempty"` // "GET", "POST", "PUT", "DELETE", etc.

	// Contexts specifies which contexts this rule applies to.
	Contexts []string `json:"contexts,omitempty"` // "public", "internal", "partner"

	// IncludePatterns are JSONPath expressions for targeted application.
	IncludePatterns []string `json:"includePatterns,omitempty"`

	// ExcludePatterns are JSONPath expressions for exclusion.
	ExcludePatterns []string `json:"excludePatterns,omitempty"`
}

type RuleOverride struct {
	// Severity overrides the rule's severity.
	Severity *Severity `json:"severity,omitempty"`
	// Disabled completely disables the rule.
	Disabled bool `json:"disabled,omitempty"`
	// Rationale provides context for the override.
	Rationale string `json:"rationale,omitempty"`
}

type RuleRelation struct {
	// RuleID is the related rule identifier.
	RuleID string `json:"ruleId"`

	// Type specifies the relationship type.
	Type string `json:"type"` // "requires", "conflicts", "supersedes", "related"

	// Description explains the relationship.
	Description string `json:"description,omitempty"`
}

type Scope string

type Section struct {
	// ID is a unique identifier for the section.
	ID string `json:"id"`

	// Title is the section heading.
	Title string `json:"title"`

	// Description provides a brief summary of the section.
	Description string `json:"description,omitempty"`

	// Order determines display ordering (lower = first).
	Order int `json:"order,omitempty"`

	// ParentID references a parent section for hierarchy.
	ParentID string `json:"parentId,omitempty"`

	// Rules lists rule IDs contained in this section.
	Rules []string `json:"rules,omitempty"`

	// Patterns lists pattern IDs contained in this section.
	Patterns []string `json:"patterns,omitempty"`

	// Introduction is introductory content for the section (Markdown).
	Introduction string `json:"introduction,omitempty"`

	// Content is the main section content (Markdown).
	Content string `json:"content,omitempty"`
}

type Severity string

type SpecMetadata struct {
	// Author is the creator of this specification.
	Author string `json:"author,omitempty"`
	// License is the license for this specification.
	License string `json:"license,omitempty"`
	// Repository is the source repository URL.
	Repository string `json:"repository,omitempty"`
	// Website is a documentation website URL.
	Website string `json:"website,omitempty"`
	// URL is an alias for website/repository for external reference.
	URL string `json:"url,omitempty"`
	// Contact is contact information.
	Contact string `json:"contact,omitempty"`
	// LastUpdated is when the specification was last modified.
	LastUpdated string `json:"lastUpdated,omitempty"`
}

type SpectralThen struct {
	// Field is the field to check within the matched node.
	Field string `json:"field,omitempty"`
	// Function is the assertion function to apply.
	Function string `json:"function,omitempty"`
	// FunctionOptions are options for the function.
	FunctionOptions map[string]string `json:"functionOptions,omitempty"`
}

type Status string

type Violation struct {
	// RuleID is the identifier of the violated rule.
	RuleID string `json:"ruleId"`

	// Severity indicates the importance of this violation.
	Severity Severity `json:"severity"`

	// Message describes what went wrong.
	Message string `json:"message"`

	// Path is the JSONPath to the violation location.
	Path string `json:"path"`

	// Line is the line number in the source file (1-indexed).
	Line int `json:"line,omitempty"`

	// Column is the column number in the source file (1-indexed).
	Column int `json:"column,omitempty"`

	// EndLine is the ending line for multi-line issues.
	EndLine int `json:"endLine,omitempty"`

	// EndColumn is the ending column for multi-line issues.
	EndColumn int `json:"endColumn,omitempty"`

	// Suggestion provides guidance for fixing the violation.
	Suggestion string `json:"suggestion,omitempty"`

	// RuleTitle is the human-readable rule name.
	RuleTitle string `json:"ruleTitle,omitempty"`

	// Category is the rule's category.
	Category string `json:"category,omitempty"`
}

type ViolationSummary struct {
	// Errors is the count of error-severity violations.
	Errors int `json:"errors"`
	// Warnings is the count of warning-severity violations.
	Warnings int `json:"warnings"`
	// Infos is the count of info-severity violations.
	Infos int `json:"infos"`
	// Hints is the count of hint-severity violations.
	Hints int `json:"hints"`
	// Total is the sum of all violations.
	Total int `json:"total"`
}