apilive

type Condition struct {
	// Kind is Grape's own class name for it: BlockCondition for a lambda,
	// HashCondition for `if: {…}`, SymbolCondition for `if: :option`.
	Kind string `json:"kind"`
	// Inverse is true for `unless:`.
	Inverse bool `json:"inverse,omitempty"`
	// File and Line locate a block condition's lambda, repository relative.
	// A hash or a symbol condition carries neither: grape-entity keeps the
	// options it tests and nothing about where the exposure declaring it was
	// written, and the exposure records no location of its own either.
	File string `json:"file,omitempty"`
	Line int    `json:"line,omitempty"`
	// Text is those lines read back from inside the image and squeezed onto
	// one. A Proc knows where it was written and not what it says, so this is
	// the only way the condition arrives readable, and it is what a rule
	// classifies on.
	Text string `json:"text,omitempty"`
	// Hash is a hash condition's own data, as Ruby inspects it: the options
	// the presenter must be given, and the values they must hold.
	Hash string `json:"hash,omitempty"`
	// Symbol is a symbol condition's option, without its colon: the field is
	// sent when the presenter is given that option with a truthy value, which
	// is a choice of the endpoint rendering it and never of the entity.
	Symbol string `json:"symbol,omitempty"`
}

type Document struct {
	SchemaVersion int    `json:"schema_version"`
	Note          string `json:"note"`
	Source        Source `json:"source"`
	// Entities is every API::Entities class the instance had loaded, keyed by
	// its Ruby name (API::Entities::Project). OpenAPIName translates that to
	// the spelling the OpenAPI record uses, for a reader joining the two.
	Entities map[string]Entity `json:"entities"`
	// Routes is every endpoint Grape had mounted, in the order the router
	// holds them.
	Routes []Route `json:"routes"`
	// Features maps a licensed feature symbol to the tier that unlocks it.
	Features map[string]string `json:"features"`
}

type Entity struct {
	// Error is set when the class refused to describe itself, which is a fact
	// about that class rather than a reason to drop it: a silently missing
	// entity reads as one GitLab does not have.
	Error string `json:"error,omitempty"`
	// Fields are the exposures in declaration order, with everything the
	// class inherits already flattened in, because root_exposures answers for
	// the class as it will render.
	Fields []Field `json:"fields,omitempty"`
}

type Field struct {
	// Name is the key GitLab sends.
	Name string `json:"name"`
	// Attribute is the method the value comes from, recorded only when `as:`
	// made it differ from Name: the key is what a client sees and the
	// attribute is what a reader greps the source for.
	Attribute string `json:"attribute,omitempty"`
	// Using names the entity the value renders with, in the same keying as
	// Document.Entities. It is the edge that makes the record a tree rather
	// than a list.
	Using string `json:"using,omitempty"`
	// Merge is set for an exposure whose value is merged into the object
	// around it instead of being placed under Name: `expose :user, merge:
	// true, using: UserBasic` on a member sends the user's own keys on the
	// member, and no `user` key at all.
	//
	// Recording it is what keeps the record from reading as the opposite of
	// what GitLab sends. Without it a member said it carries a `user` object
	// and said nothing about the id, username and name it really carries, so
	// an audit reported the one key GitLab never sends as missing and the
	// nine it does send as invented.
	Merge bool `json:"merge,omitempty"`
	// Conditions gate the field. Empty means GitLab sends it with every
	// response of every endpoint that renders this entity.
	Conditions []Condition `json:"conditions,omitempty"`
}

type Gate struct {
	// If and Unless are the conditions as [Condition.Describe] renders them,
	// joined with " && " when a field carries several, since Grape requires
	// all of them to pass.
	If     string
	Unless string
	// Tier is the highest plan the conditions demand, empty when they demand
	// none.
	Tier string
	// Edition is "ee" when a condition was written under ee/, which is where
	// Enterprise prepends live.
	//
	// It is read from the condition's own file, so a field with no condition
	// has no location to answer from and reports nothing: an exposure records
	// where its lambda was written and not where the exposure itself was.
	//
	// Only a block condition has a file. A hash or a symbol condition carries
	// none, so a field gated by one of those alone never answers "ee", even
	// when the exposure was written under ee/: an epic's reference, gated by
	// `if: { with_reference: true }` in ee/lib/api/entities/epic.rb, reads
	// with no edition. Empty therefore means "no located condition said so",
	// never "written outside ee/".
	Edition string
}

type Param struct {
	Required bool   `json:"required,omitempty"`
	Type     string `json:"type,omitempty"`
	Default  string `json:"default,omitempty"`
	Desc     string `json:"desc,omitempty"`
}

type Route struct {
	Method string `json:"method"`
	// Path is Grape's origin, without the (.:format) suffix the router adds,
	// since no caller sends that.
	Path string `json:"path"`
	// Entity is what the endpoint's `desc … success/entity` annotation names,
	// which is the same annotation GitLab's OpenAPI generator reads. It can be
	// wrong about what the endpoint really presents, and being wrong in the
	// record is better than being absent: GET /keys is annotated
	// APIEntitiesUserWithAdmin and serves an SSH key with a user under it.
	Entity  string `json:"entity,omitempty"`
	Summary string `json:"summary,omitempty"`
	// Params is what the endpoint declares it accepts, keyed by name.
	Params map[string]Param `json:"params,omitempty"`
}

type Source struct {
	Image       string `json:"image"`
	Digest      string `json:"digest,omitempty"`
	Version     string `json:"version"`
	Revision    string `json:"revision,omitempty"`
	RetrievedAt string `json:"retrieved_at"`
	// SHA256 is of the introspection output as it left the container, before
	// this record wrapped it, so two runs of one image can be compared without
	// the wrapper's own fields entering the digest.
	SHA256   string `json:"sha256"`
	Entities int    `json:"entities"`
	Fields   int    `json:"fields"`
	Routes   int    `json:"routes"`
	Features int    `json:"features"`
}