apiconformance

type FamilyResult struct {
	// Family is the family name this aggregate covers (redundant with the map
	// key so the value is self-describing when serialized).
	Family string
	// Probed is the number of probes sent in this family.
	Probed int
	// Passed is the number of probes that passed.
	Passed int
	// Failed is the number of probes that did not.
	Failed int
}

type Info struct {
	// Title is the document title (info.title).
	Title string
	// Version is the contract version (info.version), the value the version
	// negotiation reports.
	Version string
}

type Operation struct {
	// OperationID is the operationId (e.g. "get-config").
	OperationID string

	// Method is the HTTP verb in lowercase (e.g. "get").
	Method string

	// Path is the path template as written in the document (e.g.
	// "/api/sessions/{id}/export").
	Path string

	// Summary is the human-readable summary.
	Summary string

	// Tags is the operation's family tags, in document order. The first entry
	// is the primary family a probe is grouped under.
	Tags []string

	// OKStatusCode is the documented 2xx status (default 200 when the document
	// lists a 200 response).
	OKStatusCode int

	// HasOKSchema is true when the documented 200 response carries a concrete
	// response schema (not just a description). Only a handful of operations
	// have one; the rest are shape-checked as "valid JSON".
	HasOKSchema bool

	// OKSchemaRef is the $ref (if any) of the 200 response schema, e.g.
	// "#/components/schemas/ErrorModel". Empty when the 200 schema is inline.
	OKSchemaRef string

	// OKSchemaSchema is the inline 200 response schema (the schema object
	// under responses."200".content.<mime>.schema), or nil when the response
	// has no concrete schema or the schema is a bare $ref.
	OKSchemaSchema map[string]any
}

type Option func(*Suite)

type Probe struct {
	// OperationID is the operation's operationId; it is what a result is
	// reported by and how a suite maps a probe back to its spec Operation.
	OperationID string

	// Method is the HTTP verb to send.
	Method string

	// Path is the concrete request path. Path parameters (if any) are
	// substituted with a safe concrete value (or the path is left empty of the
	// parameter where that is the safe form). A probe is only added when the
	// resulting request is safe to fire at a fresh workspace.
	Path string

	// Query carries the request query string values. It is empty for the
	// majority of probes; a GET that needs a query parameter to return a 200
	// (e.g. search) supplies it here.
	Query map[string]string

	// ExpectedStatus is the status the probe expects. It is 200 for every probe;
	// the field exists so the table reads as data and a future probe family can
	// expect a different 2xx without a struct change.
	ExpectedStatus int

	// Family is the probe's primary family tag, the group a per-family report
	// aggregates under.
	Family string
}

type Report struct {
	// PerFamily maps a family name to its aggregate. Only families that had at
	// least one probe appear; the map is populated from Results.
	PerFamily map[string]FamilyResult

	// Results is the per-probe outcome in probe order.
	Results []Result
}

type Result struct {
	Probe

	// Status is the HTTP status the implementation returned. It is zero when
	// the request could not be made (transport error), in which case Passed is
	// false and Reason carries the error.
	Status int

	// Passed is true when the status was in the expected 2xx range and the body
	// shape check passed.
	Passed bool

	// Reason is empty on success and a short, single-line explanation of a
	// failure (the status mismatch or the first schema violation).
	Reason string
}

type Spec struct {
	// Info holds the top-level document metadata (title and the contract
	// version).
	Info Info

	// Tags is the declared tag list (one entry per family). A family declared
	// but not yet used by any operation still appears here.
	Tags []string

	// Operations is every operation in the document, in file order.
	Operations []Operation

	// ComponentsSchemas is the raw components.schemas map. It is kept generic
	// (map[string]any) so a validator can hand it to a JSON-Schema compiler
	// and resolve $ref against the whole document.
	ComponentsSchemas map[string]any
}

type Suite struct {
	// contains filtered or unexported fields
}

type Validator struct {
	// contains filtered or unexported fields
}