specoracle

type Baseline struct {
	Missing   []string            `json:"missing"`
	Divergent map[string][]string `json:"divergent"`
}

type ContentRecord struct {
	Media  string `json:"media"`
	Schema string `json:"schema,omitempty"`
}

type Diff struct {
	Regressions  []string
	Improvements []string
}

type FamilySummary struct {
	Family    string
	Total     int
	Missing   int
	Divergent int
	Matched   int
}

type FetchOptions struct {
	// Indexes are llms.txt URLs; each lists endpoint pages as "- [Title](url): text".
	Indexes []string
	// CacheDir receives <index-slug>/<page-slug>.json files and the manifest.
	CacheDir string
	// Client is used for every request; nil means http.DefaultClient with a timeout.
	Client *http.Client
	// Concurrency bounds parallel page fetches (default 4).
	Concurrency int
	// Delay is the pause before each page request (default 200 ms).
	Delay time.Duration
	// UserAgent overrides DefaultUserAgent.
	UserAgent string
	// Retries is the number of attempts on 429 and 5xx responses (default 3).
	Retries int
}

type Inventory struct {
	GeneratedAt time.Time      `json:"generated_at"`
	Pages       int            `json:"pages"`
	Schemas     []SchemaRecord `json:"schemas"`
	Operations  []OpRecord     `json:"operations"`
	Errors      []string       `json:"errors,omitempty"`
}

type Manifest struct {
	FetchedAt time.Time       `json:"fetched_at"`
	UserAgent string          `json:"user_agent"`
	Entries   []ManifestEntry `json:"entries"`
}

type ManifestEntry struct {
	Index   string `json:"index"`
	Family  string `json:"family"`
	Title   string `json:"title"`
	URL     string `json:"url"`
	File    string `json:"file,omitempty"`
	Status  int    `json:"status,omitempty"`
	SHA256  string `json:"sha256,omitempty"`
	Skipped string `json:"skipped,omitempty"`
	Error   string `json:"error,omitempty"`
}

type OpRecord struct {
	Key        string                     `json:"key"`
	Family     string                     `json:"family"`
	Tag        string                     `json:"tag,omitempty"`
	ID         string                     `json:"id,omitempty"`
	Method     string                     `json:"method"`
	Path       string                     `json:"path"`
	Source     string                     `json:"source"`
	Params     []ParamRecord              `json:"params,omitempty"`
	Request    []ContentRecord            `json:"request,omitempty"`
	Responses  map[string][]ContentRecord `json:"responses"`
	Deprecated bool                       `json:"deprecated,omitempty"`
}

type Operation struct {
	// Key is "METHOD /full/path" with every path parameter name replaced by
	// {}, because clients never see parameter names.
	Key          string
	Family       string
	Source       string
	ID           string
	Method       string
	Path         string
	Params       []Param
	RequestMedia []string
	RequestProps []string
	// Responses maps a status code to the property paths of its JSON body.
	Responses  map[string][]string
	Deprecated bool
}

type Oracle struct {
	Ops    map[string]Operation
	Errors []string
}

type Param struct {
	Name     string
	In       string
	Required bool
	Type     string
	Enum     []string
}

type ParamRecord struct {
	Name     string   `json:"name"`
	In       string   `json:"in"`
	Required bool     `json:"required,omitempty"`
	Type     string   `json:"type,omitempty"`
	Enum     []string `json:"enum,omitempty"`
	Default  any      `json:"default,omitempty"`
}

type Report struct {
	// Missing lists operation keys JFrog documents that we do not define.
	Missing []string
	// Divergent maps an operation key to the findings against our definition.
	Divergent map[string][]string
	// Matched lists keys we define with no findings.
	Matched []string
	// Extra lists keys we define that JFrog does not document (probes, stubs).
	Extra []string
	// Families records the family of every JFrog key, for the summary.
	Families map[string]string
	// Errors carries parse problems from either side.
	Errors []string
}

type ScaffoldOptions struct {
	// CacheDir is the oracle cache.
	CacheDir string
	// Family is the cache directory (index slug) to scaffold.
	Family string
	// ServiceBase is our service prefix, for example "/artifactory". Only
	// operations whose full path starts with it are emitted; the rest are
	// listed in Result.Skipped so the author can scaffold them elsewhere.
	ServiceBase string
	// Tag is written on every operation; defaults to the family's last word.
	Tag string
	// SkipSchemas are component names the service already defines (the shared
	// error envelope, for instance); references are kept but the schema is not
	// emitted again.
	SkipSchemas []string
}

type ScaffoldResult struct {
	YAML       []byte
	Operations int
	Schemas    int
	// Skipped lists operation keys outside ServiceBase.
	Skipped []string
	// Renamed maps original schema names to the family-prefixed names used
	// because another family defines the same name with a different shape.
	Renamed map[string]string
}

type SchemaField struct {
	Name     string   `json:"name"`
	Type     string   `json:"type,omitempty"`
	Format   string   `json:"format,omitempty"`
	Ref      string   `json:"ref,omitempty"`
	Items    string   `json:"items,omitempty"`
	Enum     []string `json:"enum,omitempty"`
	Required bool     `json:"required,omitempty"`
	ReadOnly bool     `json:"read_only,omitempty"`
	// WriteOnly marks fields JFrog accepts but never returns, such as passwords.
	WriteOnly bool `json:"write_only,omitempty"`
	Nullable  bool `json:"nullable,omitempty"`
	Default   any  `json:"default,omitempty"`
}

type SchemaRecord struct {
	Family   string        `json:"family"`
	Name     string        `json:"name"`
	Type     string        `json:"type,omitempty"`
	Composed []string      `json:"composed,omitempty"`
	Fields   []SchemaField `json:"fields,omitempty"`
	Variants int           `json:"variants"`
	UsedBy   int           `json:"used_by"`
}