contracttest

type CommitStatusHarnessConfig struct{}

type Harness struct {
	// Name is the human-readable platform identifier (e.g. "GitHub").
	Name string
	// Platform is the provider.Platform constant for this backend.
	Platform provider.Platform
	// NewProvider builds a provider.Provider from the given config. The harness
	// fills in BaseURL (and, for the retry subtest, RetryConfig) before calling,
	// so the function should forward any supplied RetryConfig/Hooks rather than
	// discarding them.
	NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
	// EmptyListResponse is the JSON body the mock returns for empty lists.
	EmptyListResponse string
	// NonEmptyListResponse is the JSON body the mock returns for a non-empty
	// list, with at least one item that maps to a valid repo.
	NonEmptyListResponse string
	// Labels, when non-nil, auto-mounts the label-management suite inside
	// Run. Run enforces both directions: a platform declaring
	// Capabilities().Labels must provide this config, and a config must not
	// be provided by a platform that does not declare the capability.
	Labels *LabelsHarnessConfig
	// Issues, when non-nil, auto-mounts the issue-management suite inside
	// Run, with the same bidirectional drift checks as Labels.
	Issues *IssuesHarnessConfig
	// Reviews, when non-nil, auto-mounts the review-management suite inside
	// Run, with the same bidirectional drift checks as Labels and Issues.
	Reviews *ReviewsHarnessConfig
	// Milestones, when non-nil, auto-mounts the milestone-management suite
	// inside Run, with the same bidirectional drift checks as Labels,
	// Issues, and Reviews.
	Milestones *MilestonesHarnessConfig
	// Search, when non-nil, auto-mounts the search suite inside Run, with
	// the same bidirectional drift checks as Labels, Issues, Reviews, and
	// Milestones.
	Search *SearchHarnessConfig
	// CommitStatus, when non-nil, auto-mounts the commit-status suite inside
	// Run, with the same bidirectional drift checks as Labels, Issues,
	// Reviews, Milestones, and Search.
	CommitStatus *CommitStatusHarnessConfig
	// Releases auto-mounts the release-management suite inside Run. Unlike
	// the fields above, ReleaseManager is a core interface composed into
	// provider.Provider (every backend implements it), so there is no
	// capability-declaration drift to check — the config is mandatory and
	// the suite fails the run when it is missing.
	Releases *ReleasesHarnessConfig
}

type IssuesHarness struct {
	Name        string
	Platform    provider.Platform
	NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
	IssuesHarnessConfig
}

type IssuesHarnessConfig struct {
	// ListResponse is the JSON array for issue-list GETs. First item: number
	// 1, title "bug", state "open", milestone {number:1, title:"v1"}.
	ListResponse string
	// GetResponse is the JSON object for single-issue GETs (number 1, title
	// "bug", state "open", milestone {number:1, title:"v1"}).
	GetResponse string
	// MutateResponse is the JSON object for POST/PATCH/PUT (same shape as
	// GetResponse).
	MutateResponse string
	// CommentsResponse is the JSON array for issue-comment GETs. First item:
	// id 1, body "a comment".
	CommentsResponse string
	// LabelsResponse is the JSON array for repository-label GETs. First
	// item: id 1, name "bug", color "#4cc917".
	LabelsResponse string
	// CreateIssueAssigneesByID declares that the backend resolves issue
	// assignee usernames through a users lookup (GitLab's /users?username=
	// exact-match filter, Tencent 工蜂's /users/{username} endpoint) and
	// writes numeric assignee IDs. When set, the suite asserts the
	// lookup-then-write wire shape on CreateIssue; when unset, the create
	// subtest exercises the plain title-only wire (the default).
	CreateIssueAssigneesByID bool
}

type LabelsHarness struct {
	// Name is the human-readable platform identifier (e.g. "GitHub").
	Name string
	// Platform is the provider.Platform constant for this backend.
	Platform provider.Platform
	// NewProvider builds a provider.Provider; the harness fills in BaseURL.
	// It must construct the provider the same way the platform's main
	// harness does (including any VersionProxy wrapping for Gitea/Forgejo).
	NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
	// ListResponse is the JSON array the mock returns for GET requests
	// (label listings and name→ID resolution lookups). Its first item must
	// have name "bug" and color "#4cc917" so the suite can assert color
	// normalization.
	ListResponse string
	// MutateResponse is the JSON object the mock returns for POST/PATCH
	// requests. It must have name "bug" and color "#4cc917".
	MutateResponse string
	// IgnoresListPagination declares that the backend's list endpoint does
	// not accept pagination parameters, so the suite skips its wire-level
	// page/per-page assertion. Currently only GitCode sets this: its SDK's
	// ListIssueLabels exposes no page/page-size parameters, so ListLabels
	// silently drops ListLabelsOptions on the wire. That is a known contract
	// gap, not something the other five backends share.
	IgnoresListPagination bool
}

type LabelsHarnessConfig struct {
	// ListResponse is the JSON array the mock returns for GET requests. Its
	// first item must have name "bug" and color "#4cc917".
	ListResponse string
	// MutateResponse is the JSON object the mock returns for POST/PATCH/PUT
	// requests. It must have name "bug" and color "#4cc917".
	MutateResponse string
	// IgnoresListPagination opts the backend out of the wire-level
	// pagination assertion (see LabelsHarness.IgnoresListPagination).
	IgnoresListPagination bool
}

type MilestonesHarness struct {
	Name        string
	Platform    provider.Platform
	NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
	MilestonesHarnessConfig
}

type MilestonesHarnessConfig struct {
	// ListResponse is the JSON array for milestone-list GETs. First item:
	// the platform's addressing identifier ("number" on GitHub and Gitee,
	// "id" on GitLab, Gitea, Forgejo, GitCode, and Tencent Code) rendering
	// as the string "1", title "v1", state "open" (GitLab's wire state
	// "active" is also accepted — the backend normalizes it).
	ListResponse string
	// MutateResponse is the JSON object for POST/PATCH/PUT (same shape as
	// the first list item).
	MutateResponse string
}

type ReleaseHarness struct {
	Name        string
	Platform    provider.Platform
	NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
	ReleasesHarnessConfig
}

type ReleasesHarnessConfig struct {
	// ByTagResponse is the JSON object for single-release fetches. Required
	// shape: id 1, tag_name "v1.0.0", name "v1.0.0", body "release notes"
	// (the suite asserts the parsed TagName).
	ByTagResponse string
	// UpdateResponse is the JSON object for PATCH/PUT release updates (same
	// shape as ByTagResponse).
	UpdateResponse string
	// UpdateSendsDescriptionOnly declares that the platform's update
	// endpoint cannot carry a release name (TencentCode's update surface
	// only accepts a description): the update wire subtest then asserts the
	// "description" key instead of "name".
	UpdateSendsDescriptionOnly bool
}

type ReviewsHarness struct {
	Name        string
	Platform    provider.Platform
	NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
	ReviewsHarnessConfig
	// IgnoresRequestReviewers declares that the backend's RequestReviewers is
	// a registered ignore: the platform's reviewer API needs inputs the SDK
	// surface cannot supply (GitLab's reviewer_ids want user IDs, but the SDK
	// addresses reviewers by username and exposes no Users API to resolve
	// them), so the method documents the ignore and performs no request. The
	// wire subtest then only asserts a silent, error-free no-op — anything
	// reaching the network would mean the registration drifted.
	IgnoresRequestReviewers bool
	// IgnoresDismissal declares that the backend's DismissReview is a
	// registered stub: the platform's review surface has no dismissal
	// endpoint at all (Tencent 工蜂 review notes expose no dismiss verb), so
	// the method documents the gap and returns a provider error wrapping
	// provider.ErrNotImplemented without touching the wire. The subtest then
	// asserts exactly that registration — a successful call or any recorded
	// request would mean the stub drifted.
	IgnoresDismissal bool
	// ListStateIsCommented declares that the backend's review reads carry no
	// verdict state: the SDK model behind ListReviews/GetReview has no state
	// field (Tencent 工蜂 review notes — the verdict travels only on the
	// create/update writes as reviewer_state and never comes back), so every
	// read review normalizes to provider.ReviewStateCommented, a registered
	// limitation. The List subtest then asserts that commented normalization
	// instead of the default approved one.
	ListStateIsCommented bool
}

type ReviewsHarnessConfig struct {
	// ListResponse is the JSON array for review-list GETs. First item: id 1,
	// user login "dev", state "APPROVED" (the suite asserts normalization to
	// provider.ReviewStateApproved).
	ListResponse string
	// GetResponse is the JSON object for single-review GETs (id 1, user
	// "dev", state "APPROVED").
	GetResponse string
	// MutateResponse is the JSON object for POST/PUT/PATCH (same shape as
	// GetResponse).
	MutateResponse string
	// CreateEvent is the wire value the platform's create must carry under
	// the "event" key for the suite's APPROVE-verdict create. The suite
	// calls CreateReview with Event "APPROVE": GitHub and GitCode forward
	// the option verbatim ("APPROVE"), Gitea/Forgejo translate it to their
	// SDK's review state ("APPROVED"). Empty means the platform's create
	// carries no verdict on the wire (GitLab's note-based create) and the
	// event-key assertion is skipped — the body assertion still runs.
	CreateEvent string
	// IgnoresRequestReviewers opts the backend out of the RequestReviewers
	// wire assertion (see ReviewsHarness.IgnoresRequestReviewers).
	IgnoresRequestReviewers bool
	// RequestReviewersByID declares that the backend resolves reviewer
	// usernames to numeric user IDs through a /users lookup before writing
	// them (GitLab resolves usernames to IDs first): the wire subtest then
	// asserts the lookup GET and an ID-carrying update body instead of the
	// username-carrying create (see assertRequestReviewersByIDWire).
	RequestReviewersByID bool
	// IgnoresDismissal opts the backend out of the DismissReview verb
	// assertion (see ReviewsHarness.IgnoresDismissal). It is for platforms
	// whose ONLY dismissal gap is a registered stub: the platform exposes no
	// dismiss surface at all, so DismissReview returns a wrapped
	// provider.ErrNotImplemented and the subtest asserts that registration
	// instead of a state-changing verb.
	IgnoresDismissal bool
	// ListStateIsCommented declares that the platform's review reads cannot
	// carry a verdict state (see ReviewsHarness.ListStateIsCommented).
	ListStateIsCommented bool
}

type SearchHarness struct {
	Name        string
	Platform    provider.Platform
	NewProvider func(t *testing.T, cfg provider.Config) provider.Provider
	SearchHarnessConfig
}

type SearchHarnessConfig struct {
	// ReposResponse is the JSON body for repository-search GETs, in the
	// platform's wire shape (GitHub wraps items in {"total_count":..,
	// "items":[..]}, Gitea/Forgejo in {"data":[..]}, the rest are bare
	// arrays).
	ReposResponse string
	// ReposTotalCount is the server-side total the repos fixture reports
	// (GitHub's envelope carries total_count; the suite then asserts
	// SearchRepos returns exactly this total). Zero means the platform
	// reports no server-side total — the backend returns nil for total and
	// the suite keeps the weaker total == nil || *total >= len(results)
	// assertion.
	ReposTotalCount int
	// IssuesResponse is the JSON body for issue-search GETs, same per-
	// platform wrapping rules as ReposResponse.
	IssuesResponse string
	// UsersResponse is the JSON body for user-search GETs, same per-
	// platform wrapping rules as ReposResponse.
	UsersResponse string
}