model

type BuildWarning struct {
	Message string
	Context string // e.g. path, component name
	Err     error
}

type CallbackInfo struct {
	Name       string                   `json:"name"`
	Ref        *ComponentLink           `json:"ref,omitempty"`
	Operations []*CallbackOperationInfo `json:"operations"`
}

type CallbackOperationInfo struct {
	Expression  string           `json:"expression"`
	Method      string           `json:"method"`
	Description string           `json:"description,omitempty"`
	DescHTML    string           `json:"descHtml,omitempty"`
	RequestBody *RequestBodyInfo `json:"requestBody,omitempty"`
	Responses   []*ResponseInfo  `json:"responses,omitempty"`
}

type CatalogService struct {
	Key             string            `json:"key"`
	Slug            string            `json:"slug"`
	DisplayName     string            `json:"displayName"`
	Summary         string            `json:"summary,omitempty"`
	PrimaryPath     string            `json:"primaryPath,omitempty"`
	SpecCount       int               `json:"specCount"`
	OverviewHref    string            `json:"overviewHref,omitempty"`
	VersionsHref    string            `json:"versionsHref,omitempty"`
	LatestVersion   *CatalogVersion   `json:"latestVersion,omitempty"`
	Versions        []*CatalogVersion `json:"versions,omitempty"`
	CollisionGroups []string          `json:"collisionGroups,omitempty"`
	Counts          *ViolationCounts  `json:"counts,omitempty"`
}

type CatalogSite struct {
	Title        string            `json:"title,omitempty"`
	Description  string            `json:"description,omitempty"`
	ScanRoot     string            `json:"scanRoot,omitempty"`
	OutputDir    string            `json:"-"`
	BaseURL      string            `json:"-"`
	AssetMode    string            `json:"-"`
	Services     []*CatalogService `json:"services,omitempty"`
	ContentPages []*ContentPage    `json:"contentPages,omitempty"`
	Warnings     []*BuildWarning   `json:"warnings,omitempty"`
}

type CatalogSpecEntry struct {
	ID            string             `json:"id"`
	Slug          string             `json:"slug"`
	Title         string             `json:"title,omitempty"`
	Summary       string             `json:"summary,omitempty"`
	Contact       *ContactInfo       `json:"contact,omitempty"`
	ServiceKey    string             `json:"serviceKey,omitempty"`
	ServiceSlug   string             `json:"serviceSlug,omitempty"`
	Version       string             `json:"version,omitempty"`
	VersionSlug   string             `json:"versionSlug,omitempty"`
	Format        string             `json:"format,omitempty"`
	RelativePath  string             `json:"relativePath,omitempty"`
	OutputSubdir  string             `json:"outputSubdir,omitempty"`
	OverviewHref  string             `json:"overviewHref,omitempty"`
	RenderSkipped bool               `json:"renderSkipped,omitempty"`
	Warnings      []string           `json:"warnings,omitempty"`
	Source        *SourceRef         `json:"source,omitempty"`
	HeaderContext *SiteHeaderContext `json:"headerContext,omitempty"`
	Counts        *ViolationCounts   `json:"counts,omitempty"`
}

type CatalogVersion struct {
	Label        string              `json:"label"`
	Slug         string              `json:"slug"`
	Summary      string              `json:"summary,omitempty"`
	OverviewHref string              `json:"overviewHref,omitempty"`
	SpecCount    int                 `json:"specCount"`
	IsLatest     bool                `json:"isLatest,omitempty"`
	Entries      []*CatalogSpecEntry `json:"entries,omitempty"`
	Counts       *ViolationCounts    `json:"counts,omitempty"`
}

type CodeSample struct {
	Lang            string `json:"lang,omitempty"`
	Label           string `json:"label,omitempty"`
	Source          string `json:"source"`
	SourceRef       string `json:"sourceRef,omitempty"`
	HighlightedHTML string `json:"-"`
}

type ComponentLink struct {
	Name          string `json:"name"`          // original component name
	ComponentType string `json:"componentType"` // ref segment e.g. "responses"
	TypeSlug      string `json:"typeSlug"`      // URL segment e.g. "responses", "request-bodies"
	Slug          string `json:"slug"`          // URL-safe slug for the model page
}

type ComponentRef struct {
	Name          string `json:"name"`
	ComponentType string `json:"componentType"`
	TypeSlug      string `json:"typeSlug"` // URL path segment: "request-bodies", "path-items", etc.
	Slug          string `json:"slug"`
}

type ContactInfo struct {
	Name  string `json:"name,omitempty"`
	URL   string `json:"url,omitempty"`
	Email string `json:"email,omitempty"`
}

type ContentPage struct {
	Title       string              `json:"title"`
	Label       string              `json:"label,omitempty"`
	Slug        string              `json:"slug"`
	Href        string              `json:"href"`
	Description string              `json:"description,omitempty"`
	SourcePath  string              `json:"-"`
	SourceDir   string              `json:"-"`
	SourceAlias []string            `json:"-"`
	Body        string              `json:"-"`
	BodyHTML    string              `json:"bodyHtml,omitempty"`
	Order       int                 `json:"order,omitempty"`
	Hidden      bool                `json:"hidden,omitempty"`
	Assets      []*ContentPageAsset `json:"-"`
}

type ContentPageAsset struct {
	Href       string `json:"href"`
	SourcePath string `json:"-"`
	Data       []byte `json:"-"`
}

type CurlVariant struct {
	Label             string `json:"label"`
	ServerURL         string `json:"serverUrl"`
	ServerDescription string `json:"serverDescription,omitempty"`
	SecurityLabel     string `json:"securityLabel,omitempty"`
	Command           string `json:"command"`
}

type DiagnosticsPage struct {
	Title       string          `json:"title"`
	Slug        string          `json:"slug"`
	SiteCounts  ViolationCounts `json:"siteCounts"`
	Problems    []*PageProblem  `json:"problems"`
	OrphanCount int             `json:"orphanCount"`
}

type ExtensionEntry struct {
	Key   string `json:"key"`
	Value any    `json:"value"`
}

type ExternalDocInfo struct {
	URL         string
	Description string
}

type FooterConfig struct {
	Disabled  bool   `json:"disabled,omitempty"`
	URL       string `json:"url,omitempty"`
	LinkTitle string `json:"linkTitle,omitempty"`
	Build     string `json:"build,omitempty"`
}

type HeaderInfo struct {
	Name        string            `json:"name"`
	Description string            `json:"description,omitempty"`
	SchemaType  string            `json:"schemaType,omitempty"`
	Ref         *ComponentLink    `json:"ref,omitempty"`
	Example     string            `json:"example,omitempty"`
	Minimum     *float64          `json:"minimum,omitempty"`
	Maximum     *float64          `json:"maximum,omitempty"`
	Default     string            `json:"default,omitempty"`
	Enum        []string          `json:"enum,omitempty"`
	Pattern     string            `json:"pattern,omitempty"`
	Extensions  []*ExtensionEntry `json:"extensions,omitempty"`
}

type LLMOutputConfig struct {
	AggregateSpecSizeThresholdBytes int64
	MaxAggregateFileBytes           int64
	GenerateMonoliths               string
}

type LicenseInfo struct {
	Name string
	URL  string
}

type LinkInfo struct {
	Name          string         `json:"name"`
	OperationId   string         `json:"operationId,omitempty"`
	OperationSlug string         `json:"operationSlug,omitempty"`
	OperationRef  string         `json:"operationRef,omitempty"`
	Description   string         `json:"description,omitempty"`
	Ref           *ComponentLink `json:"ref,omitempty"`
}

type MediaTypeInfo struct {
	MediaType             string            `json:"mediaType"`
	SchemaJSON            string            `json:"schemaJson"`
	SchemaHighlightedHTML string            `json:"-"` // chroma output, templ only
	MockJSON              string            `json:"mockJson,omitempty"`
	MockYAML              string            `json:"mockYaml,omitempty"`
	MockXML               string            `json:"mockXml,omitempty"`
	Examples              map[string]string `json:"examples,omitempty"`
	SchemaRef             *ComponentLink    `json:"schemaRef,omitempty"`
	IsArray               bool              `json:"isArray,omitempty"`
	ItemsRef              *ComponentLink    `json:"itemsRef,omitempty"`
	ItemsSchemaJSON       string            `json:"itemsSchemaJson,omitempty"`
	Extensions            []*ExtensionEntry `json:"extensions,omitempty"`
}

type ModelCrossRefs struct {
	UsedByOperations []*OperationRef `json:"usedByOperations,omitempty"`
	UsedByModels     []*ComponentRef `json:"usedByModels,omitempty"`
	UsesModels       []*ComponentRef `json:"usesModels,omitempty"`
}

type ModelPage struct {
	Name                     string
	ComponentType            string // "schemas", "responses", "parameters", etc.
	TypeSlug                 string // URL path segment for the component type
	Slug                     string
	Description              string
	DescHTML                 string
	SchemaJSON               string // JSON representation for cowboy-components rendering
	SchemaHighlightedHTML    string `json:"-"` // chroma output, templ only
	RawYAML                  string `json:"-"` // re-rendered YAML from Render(), for raw viewer
	SchemaRawYAML            string `json:"-"` // schema-only YAML for inline viewer (parameters, headers)
	SchemaRawJSON            string `json:"-"` // schema-only JSON for inline viewer (parameters, headers)
	SchemaStartLine          int    `json:"-"` // 1-based source line where schema content begins (parameters, headers)
	MockJSON                 string
	Examples                 map[string]string
	ExamplesJSON             string // pre-serialized for Lit component
	Origin                   *bundler.ComponentOrigin
	Source                   *SourceRef `json:"source,omitempty"`
	Extensions               []*ExtensionEntry
	ExtensionsJSON           string `json:"-"`
	CrossRefs                *ModelCrossRefs
	CrossRefsJSON            string `json:"-"`
	MermaidDiagram           string `json:"-"` // mermaid class diagram DSL; empty if no relationships
	GraphJSON                string `json:"-"` // pre-filtered dependency subgraph for explorer
	GraphNodeID              string `json:"-"` // exact JSONPath node ID for POV focus
	LayoutMode               string `json:"-"` // simple, stacked, or split
	EstimatedBodyHeight      int    `json:"-"`
	EstimatedSplitHeight     int    `json:"-"`
	EstimatedCrossRefsHeight int    `json:"-"`
	PropertyCount            int    `json:"-"`
	RequiredCount            int    `json:"-"`
	HasExamplePayload        bool   `json:"-"`
	Counts                   ViolationCounts
	Problems                 []*PageProblem
	Slices                   map[string]*YamlSlice
}

type NavModel struct {
	Name        string           `json:"name"`
	Slug        string           `json:"slug"`
	TypeSlug    string           `json:"typeSlug"`
	Description string           `json:"description,omitempty"`
	Counts      *ViolationCounts `json:"counts,omitempty"`
}

type NavModelGroup struct {
	Name         string           `json:"name"`
	TypeSlug     string           `json:"typeSlug"`
	Models       []*NavModel      `json:"models"`
	CardMinWidth int              `json:"cardMinWidth,omitempty"`
	Counts       *ViolationCounts `json:"counts,omitempty"`
}

type NavOperation struct {
	Method      string           `json:"method"`
	Path        string           `json:"path"`
	OperationID string           `json:"operationId"`
	Summary     string           `json:"summary"`
	Slug        string           `json:"slug"`
	Deprecated  bool             `json:"deprecated"`
	Counts      *ViolationCounts `json:"counts,omitempty"`
}

type NavTag struct {
	Name        string           `json:"name"`
	Summary     string           `json:"summary"`
	Slug        string           `json:"slug"`
	Description string           `json:"description,omitempty"`
	DescHTML    string           `json:"-"`
	Children    []*NavTag        `json:"children"`
	Operations  []*NavOperation  `json:"operations"`
	IsNavOnly   bool             `json:"isNavOnly"` // kind: nav (grouping node with no direct operations)
	Counts      *ViolationCounts `json:"counts,omitempty"`
}

type OperationCrossRefs struct {
	ReferencesModels []*ComponentRef `json:"referencesModels,omitempty"` // components this operation uses
}

type OperationPage struct {
	Method                string
	Path                  string
	OperationID           string
	Summary               string
	Description           string
	DescHTML              string
	Tags                  []string
	TagPath               []string // hierarchical tag path from root to leaf (summaries)
	TagSlugs              []string // parallel to TagPath: slug for each tag's index page
	Deprecated            bool
	Slug                  string
	Parameters            []*ParameterInfo
	ParametersJSON        string `json:"-"` // pre-serialized for Lit component; excluded from JSON writer
	RequestBody           *RequestBodyInfo
	Responses             []*ResponseInfo
	ResponsesJSON         string `json:"-"` // pre-serialized for Lit component; excluded from JSON writer
	CommonHeaders         []*HeaderInfo
	CommonHeadersJSON     string `json:"-"` // pre-serialized for templ rendering
	Security              []*SecurityRequirement
	SecurityGroups        []*SecurityRequirementGroup `json:"securityGroups,omitempty"`
	HasSecurityOverride   bool                        `json:"-"`
	Servers               []*ServerInfo
	ExternalDoc           *ExternalDocInfo
	CurlJSON              string            `json:"curlJson,omitempty"`
	CodeSamples           []*CodeSample     `json:"codeSamples,omitempty"`
	Extensions            []*ExtensionEntry `json:"extensions,omitempty"`
	ExtensionsJSON        string            `json:"-"` // pre-serialized for Lit component
	PathExtensions        []*ExtensionEntry `json:"pathExtensions,omitempty"`
	PathExtensionsJSON    string            `json:"-"`
	Callbacks             []*CallbackInfo   `json:"callbacks,omitempty"`
	CallbacksJSON         string            `json:"-"` // pre-serialized for Lit component
	SchemaJSON            string            // full operation rendered as JSON for cowboy-components
	SchemaHighlightedHTML string            `json:"-"` // chroma output, templ only
	RawYAML               string            `json:"-"` // re-rendered YAML from Render(), for raw viewer
	SourceLine            int               `json:"-"` // 1-based YAML line number of the operation
	Location              string            `json:"-"` // source file path for multi-file specs
	Source                *SourceRef        `json:"source,omitempty"`
	CrossRefs             *OperationCrossRefs
	Counts                ViolationCounts
	Problems              []*PageProblem
	Slices                map[string]*YamlSlice
}

type OperationRef struct {
	Method string `json:"method"`
	Path   string `json:"path"`
	Slug   string `json:"slug"`
}

type PageProblem struct {
	Category        string `json:"category"`
	JSONPath        string `json:"jsonPath"`
	EndColumn       int    `json:"endColumn"`
	EndLineNumber   int    `json:"endLineNumber"`
	Message         string `json:"message"`
	Severity        int    `json:"severity"`
	StartColumn     int    `json:"startColumn"`
	StartLineNumber int    `json:"startLineNumber"`
	Source          string `json:"source"`
	ID              string `json:"id"`
	SourceLocation  string `json:"sourceLocation"`
	PageHref        string `json:"pageHref,omitempty"`
	PageTitle       string `json:"pageTitle,omitempty"`
	PageKind        string `json:"pageKind,omitempty"`
	PageMethod      string `json:"pageMethod,omitempty"`
	PagePath        string `json:"pagePath,omitempty"`
	PageOperationID string `json:"pageOperationId,omitempty"`
	PageComponent   string `json:"pageComponent,omitempty"`
	SliceKey        string `json:"sliceKey,omitempty"`
}

type ParameterInfo struct {
	Name        string            `json:"name"`
	In          string            `json:"in"`
	Description string            `json:"description"`
	Required    bool              `json:"required"`
	Deprecated  bool              `json:"deprecated"`
	SchemaJSON  string            `json:"schemaJson"`
	MockJSON    string            `json:"mockJson,omitempty"`
	Examples    map[string]string `json:"examples,omitempty"`
	Ref         *ComponentLink    `json:"ref,omitempty"`
	RawJSON     string            `json:"rawJson,omitempty"`
	RawYAML     string            `json:"rawYaml,omitempty"`
	SourceLine  int               `json:"sourceLine,omitempty"`
	Location    string            `json:"location,omitempty"`
	Source      *SourceRef        `json:"source,omitempty"`
	Extensions  []*ExtensionEntry `json:"extensions,omitempty"`
}

type RequestBodyInfo struct {
	Description    string            `json:"description,omitempty"`
	DescHTML       string            `json:"descHtml,omitempty"`
	Required       bool              `json:"required,omitempty"`
	Content        []*MediaTypeInfo  `json:"content,omitempty"`
	Ref            *ComponentLink    `json:"ref,omitempty"`
	RawJSON        string            `json:"rawJson,omitempty"`
	RawYAML        string            `json:"rawYaml,omitempty"`
	SourceLine     int               `json:"sourceLine,omitempty"`
	Location       string            `json:"location,omitempty"`
	Source         *SourceRef        `json:"source,omitempty"`
	Extensions     []*ExtensionEntry `json:"extensions,omitempty"`
	ExtensionsJSON string            `json:"-"`
}

type ResponseInfo struct {
	StatusCode  string            `json:"statusCode"`
	Description string            `json:"description"`
	DescHTML    string            `json:"descHtml,omitempty"`
	Content     []*MediaTypeInfo  `json:"content,omitempty"`
	Headers     []*HeaderInfo     `json:"headers,omitempty"`
	Links       []*LinkInfo       `json:"links,omitempty"`
	Ref         *ComponentLink    `json:"ref,omitempty"`
	RawJSON     string            `json:"rawJson,omitempty"`
	RawYAML     string            `json:"rawYaml,omitempty"`
	SourceLine  int               `json:"sourceLine,omitempty"`
	Location    string            `json:"location,omitempty"`
	Source      *SourceRef        `json:"source,omitempty"`
	Extensions  []*ExtensionEntry `json:"extensions,omitempty"`
}

type RootPage struct {
	Title              string
	Description        string
	DescHTML           string
	Version            string
	Contact            *ContactInfo
	License            *LicenseInfo
	Servers            []*ServerInfo
	Security           []*SecurityRequirement
	SecurityGroups     []*SecurityRequirementGroup `json:"securityGroups,omitempty"`
	ExternalDoc        *ExternalDocInfo
	TagTree            []*NavTag
	UntaggedOperations []*NavOperation
	Webhooks           []*NavOperation
	Warnings           []*BuildWarning
	Source             *SourceRef `json:"source,omitempty"`
	Counts             ViolationCounts
	Problems           []*PageProblem
	Slices             map[string]*YamlSlice
}

type SchemaRegistryEntry struct {
	Name          string `json:"name"`
	ComponentType string `json:"componentType"`
	Description   string `json:"description,omitempty"`
	SchemaJSON    string `json:"schemaJson"`
	MockJSON      string `json:"mockJson,omitempty"`
}

type SecurityRequirement struct {
	Name          string         `json:"name"`
	Scopes        []string       `json:"scopes,omitempty"`
	SchemeType    string         `json:"schemeType,omitempty"`    // apiKey, http, oauth2, openIdConnect
	In            string         `json:"in,omitempty"`            // query, header, cookie (for apiKey)
	Scheme        string         `json:"scheme,omitempty"`        // bearer, basic (for http)
	ParameterName string         `json:"parameterName,omitempty"` // actual apiKey parameter/header/cookie name
	Ref           *ComponentLink `json:"ref,omitempty"`           // link to model page
}

type SecurityRequirementGroup struct {
	Requirements []*SecurityRequirement `json:"requirements,omitempty"`
}

type ServerInfo struct {
	URL         string
	Description string
	Variables   []*ServerVariableInfo `json:"variables,omitempty"`
}

type ServerVariableInfo struct {
	Name        string   `json:"name"`
	Default     string   `json:"default,omitempty"`
	Enum        []string `json:"enum,omitempty"`
	Description string   `json:"description,omitempty"`
}

type Site struct {
	Root               *RootPage
	Operations         []*OperationPage
	ContentPages       []*ContentPage
	Models             map[string][]*ModelPage // keyed by component type slug (e.g. "schemas")
	Webhooks           []*OperationPage
	Diagnostics        *DiagnosticsPage
	OrphanResults      []*v3.RuleFunctionResult `json:"-"`
	Embedded           bool                     `json:"embedded,omitempty"`
	DeveloperMode      bool                     `json:"developerMode,omitempty"`
	HostedDocumentID   string                   `json:"hostedDocumentId,omitempty"`
	DocsExpiresAt      string                   `json:"docsExpiresAt,omitempty"`
	ArchiveExportURL   string                   `json:"-"`
	NavTags            []*NavTag
	NavModelGroups     []*NavModelGroup
	NavWebhooks        []*NavOperation `json:"-"` // webhook nav entries
	Warnings           []*BuildWarning
	SpecFormat         string                          // "yaml" or "json" — the input spec format
	SchemaRegistry     map[string]*SchemaRegistryEntry `json:"-"` // keyed by "componentType/name"
	Lite               bool                            // when true, use lite JS bundle (no mermaid/explorer)
	NoMermaid          bool                            // when true, suppress inline mermaid rendering
	OutputDir          string                          `json:"-"` // default writer output directory from config
	BaseURL            string                          `json:"-"` // default HTML base URL from config
	AssetMode          string                          `json:"-"` // html hydration asset mode: portable or served
	SharedAssetBaseURL string                          `json:"-"` // when set, shared assets are referenced at this URL prefix and not copied into the artifact
	SourceSizeBytes    int64                           `json:"-"` // root source size used for large-spec LLM aggregate policy
	LLM                LLMOutputConfig                 `json:"-"` // resolved LLM writer policy
	Footer             *FooterConfig                   `json:"footer,omitempty"`
	Source             *SourceRef                      `json:"source,omitempty"`
	HeaderContext      *SiteHeaderContext              `json:"headerContext,omitempty"`
}

type SiteHeaderContext struct {
	CatalogHref    string             `json:"catalogHref,omitempty"`
	OverviewHref   string             `json:"overviewHref,omitempty"`
	ServiceName    string             `json:"serviceName,omitempty"`
	CurrentVersion string             `json:"currentVersion,omitempty"`
	VersionsHref   string             `json:"versionsHref,omitempty"`
	Versions       []*SiteVersionLink `json:"versions,omitempty"`
}

type SiteVersionLink struct {
	Label  string `json:"label"`
	Href   string `json:"href"`
	Active bool   `json:"active,omitempty"`
}

type SourceRef struct {
	Path string `json:"path,omitempty"`
	Line int    `json:"line,omitempty"`
	Href string `json:"href,omitempty"`
}

type ViolationCounts struct {
	Errors int `json:"errors"`
	Warns  int `json:"warns"`
	Infos  int `json:"infos"`
}

type YamlSlice struct {
	Key          string `json:"key"`
	File         string `json:"file"`
	FirstLine    int    `json:"firstLine"`
	Source       string `json:"source,omitempty"`
	LastLine     int    `json:"-"`
	ResolvedFile string `json:"-"`
}