contracttest

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

type BranchProtectionsHarnessConfig struct {
	ListResponse   string
	MutateResponse string
}

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

type CollaboratorsHarnessConfig struct {
	ListResponse string
	// UserLookupResponse, when set, is served for the username→ID lookup
	// GET (…/users/{username}) that platforms with ID-addressed member
	// APIs (GitLab, TencentCode) perform before add/remove mutations.
	// Empty means the platform addresses collaborators by username
	// directly and makes no lookup.
	UserLookupResponse string
}

type CommitStatusHarnessConfig struct {
	ListResponse  string
	EmptyResponse string
}

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

type DeployKeysHarnessConfig struct {
	ListResponse   string
	CreateResponse string
}

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
	// Notifications, when non-nil, auto-mounts the notification suite inside
	// Run, with the same bidirectional drift checks.
	Notifications *NotificationsHarnessConfig
	// Reactions, when non-nil, auto-mounts the reaction suite inside
	// Run, with the same bidirectional drift checks.
	Reactions *ReactionsHarnessConfig
	// BranchProtections, when non-nil, auto-mounts the branch-protection
	// suite inside Run, with the same bidirectional drift checks.
	BranchProtections *BranchProtectionsHarnessConfig
	// Collaborators, when non-nil, auto-mounts the collaborator suite.
	Collaborators *CollaboratorsHarnessConfig
	// WebhookConfig, when non-nil, auto-mounts the single-webhook
	// get/update suite (WebhookConfigManager — all seven backends).
	WebhookConfig *WebhookConfigHarnessConfig
	// Notes, when non-nil, auto-mounts the CR-note (merge-request note)
	// read/edit suite — GitLab-family platforms where MR notes live in a
	// separate iid namespace (GitHub-family: covered by IssueManager, no
	// config expected).
	Notes *NotesHarnessConfig
	// DeployKeys, when non-nil, auto-mounts the deploy-key suite.
	DeployKeys *DeployKeysHarnessConfig
	// RepoStats, when non-nil, auto-mounts the repo-stats suite.
	RepoStats *RepoStatsHarnessConfig
	// Users, when non-nil, auto-mounts the user-manager suite.
	Users *UsersHarnessConfig
	// 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
	// UpdateCommentViaIssue declares that the backend addresses an issue
	// comment edit through the issue (GitLab, Tencent 工蜂 note APIs): the
	// suite additionally asserts the recorded edit request hits
	// issues/1/notes/1, so a swap of the number and commentID plumbing
	// fails instead of passing on the body assertion alone.
	UpdateCommentViaIssue 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 NotesHarness struct {
	Name           string
	Platform       provider.Platform
	NewProvider    func(t *testing.T, cfg provider.Config) provider.Provider
	ListResponse   string
	MutateResponse string
}

type NotesHarnessConfig struct {
	// ListResponse is the JSON array served for the notes-list GET (and
	// the empty terminal page beyond page 1). Required shape: at least
	// one note with id/body/author.username.
	ListResponse string
	// MutateResponse is the JSON object returned by the note-edit PUT.
	MutateResponse string
}

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

type NotificationsHarnessConfig struct {
	// ListResponse is the JSON array the mock returns for notification list
	// requests. It must contain at least one notification with unread=true.
	ListResponse string
}

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

type ReactionsHarnessConfig struct {
	// ListResponse is the JSON array the mock returns for reaction list
	// requests. It must contain at least one reaction with content "+1".
	ListResponse string
	// CreateResponse is the JSON object the mock returns for reaction create
	// requests.
	CreateResponse 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 RepoStatsHarness struct {
	Name                 string
	Platform             provider.Platform
	NewProvider          func(t *testing.T, cfg provider.Config) provider.Provider
	ForksResponse        string
	StargazersResponse   string
	ContributorsResponse string
}

type RepoStatsHarnessConfig struct {
	ForksResponse        string
	StargazersResponse   string
	ContributorsResponse string
}

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
}

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

type UsersHarnessConfig struct {
	// GetUserResponse is the JSON the mock returns for user lookup.
	GetUserResponse string
}

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

type WebhookConfigHarnessConfig struct {
	// GetResponse is one webhook in the platform's native wire shape. It is
	// served for both the GET (get + family read-back) and the update call,
	// so converters must be able to decode it — e.g. GitHub/GitCode
	// `{"id":42,"url":"…","events":["push"]}`, GitLab/Gitee/TencentCode
	// boolean-flag bodies, Gitea-family `{"id":42,"config":{"url":"…"}, …}`.
	GetResponse string
}

type WebhookParser interface {
	ParseWebhookEvent(r *http.Request, secret string) (*provider.NormalizedEvent, error)
}