external

type ClientError struct {
	Provider  string
	Operation string
	Err       error
}

type PRContext struct {
	// Number is the PR number.
	Number int

	// HeadSHA is the commit SHA of the PR head.
	HeadSHA string

	// BaseSHA is the commit SHA of the PR base.
	BaseSHA string

	// Branch is the PR source branch name.
	Branch string

	// BaseBranch is the PR target branch name.
	BaseBranch string

	// Author is the PR author username.
	Author string

	// Title is the PR title.
	Title string

	// Repository is the repository name (e.g., "owner/repo").
	Repository string
}

type Provider string

type ProviderConfig struct {
	// Type identifies the provider (jenkins, github-actions, gitlab).
	Type string

	// Endpoint is the base URL for the CI system API.
	// Examples:
	//   - Jenkins: "https://jenkins.example.com"
	//   - GitLab: "https://gitlab.example.com/api/v4"
	//   - GitHub Actions: "https://api.github.com"
	Endpoint string

	// Token is the API authentication token.
	// Should be loaded from Kubernetes Secrets, not stored in config files.
	Token string

	// Username is the username for basic auth (Jenkins only).
	// GitHub Actions and GitLab use token-only auth.
	Username string

	// Timeout is the default timeout for API requests.
	// Zero means use the package default (30 seconds).
	Timeout time.Duration

	// Additional provider-specific configuration can be stored here.
	// Examples: TLS settings, proxy configuration, etc.
	Extra map[string]string
}

type SubstitutionContext struct {
	// PR contains pull request metadata.
	PR PRContext

	// Environment is the deployment environment (e.g., "staging", "production").
	Environment string

	// Version is the application version being tested.
	Version string

	// Cluster is the Kubernetes cluster name.
	Cluster string

	// Namespace is the Kubernetes namespace.
	Namespace string

	// Custom allows arbitrary key-value substitutions.
	// Keys should be namespaced (e.g., "custom.my_value").
	Custom map[string]string
}

type TestConfig struct {
	// JobName is the name of the test job, workflow, or pipeline to trigger.
	// Format is provider-specific (see struct documentation above).
	JobName string

	// Parameters contains job/workflow parameters as key-value pairs.
	// These are passed to the CI system and may include:
	//   - ENVIRONMENT: target environment (dev/staging/prod)
	//   - VERSION: version to test
	//   - COMMIT_SHA: Git commit SHA to test
	// Supports variable substitution (${pr.number}, ${pr.head.sha}, ${cd.version}, etc.)
	Parameters map[string]string

	// Ref is the Git reference (SHA, branch, tag) to test.
	// For GitHub Actions, this determines which workflow file version to use.
	// For Jenkins/GitLab, this may be passed as a parameter.
	Ref string

	// Timeout is the maximum duration to wait for test completion.
	// If the test doesn't complete within this time, it's marked as timed out.
	// Zero means use the provider's default timeout.
	Timeout time.Duration

	// Provider identifies the CI system (Jenkins, GitHubActions, GitLab).
	Provider Provider

	// ProviderConfig holds provider-specific configuration (repo, branch, etc).
	// Contents depend on the Provider value.
	ProviderConfig map[string]string
}

type TestResult struct {
	// Passed indicates whether all tests passed.
	Passed bool

	// Duration is the total test execution time.
	Duration time.Duration

	// FailureReason explains why tests failed (empty if Passed is true).
	FailureReason string

	// TestsPassed is the number of test cases that passed.
	TestsPassed int

	// TestsFailed is the number of test cases that failed.
	TestsFailed int

	// Artifacts contains URLs to generated artifacts (coverage, reports, etc).
	Artifacts map[string]string
}

type TestRun struct {
	// ID is the unique identifier for this test run in the CI system.
	// Used for status polling and log retrieval.
	// Format is provider-specific:
	//   - Jenkins: build number (e.g., "123")
	//   - GitHub Actions: run ID (e.g., "1234567890")
	//   - GitLab CI: pipeline ID (e.g., "987654321")
	ID string

	// Provider identifies the CI system (jenkins, github-actions, gitlab).
	// Used to route status checks to the correct TestRunner implementation.
	Provider Provider

	// JobName is the name of the job/workflow that was triggered.
	// Copied from TestConfig for reference.
	JobName string

	// URL is the web UI link to view the test run.
	// Displayed in GitHub PR comments and operator logs.
	URL string

	// StartedAt is when the test run was triggered.
	// Used for timeout calculations and metrics.
	StartedAt time.Time

	// CompletedAt is when the test run finished (success, failure, or timeout).
	// Zero value means the test is still running.
	CompletedAt time.Time

	// Status is the current status of the test run.
	Status TestStatus

	// Message contains additional context about the test run.
	// May include error messages, failure reasons, or summary information.
	Message string
}

type TestRunner interface {
	// TriggerTest starts a test job/workflow with the given configuration.
	// Returns a TestRun with the run ID and metadata needed for status polling.
	//
	// Common errors:
	//   - ErrAuthFailed: Authentication credentials are invalid
	//   - ErrTriggerFailed: Job trigger failed (job not found, invalid params)
	//   - context.DeadlineExceeded: Operation timeout
	TriggerTest(ctx context.Context, config TestConfig) (*TestRun, error)

	// GetStatus polls the current status of a running test.
	// Returns the current TestStatus and any error encountered during polling.
	// Should be called periodically until status is terminal (success/failure/timeout).
	// Implementations should be idempotent - safe to call repeatedly.
	//
	// Common errors:
	//   - ErrTestNotFound: Test run ID doesn't exist or expired
	//   - ErrAuthFailed: Authentication credentials are invalid
	//   - context.DeadlineExceeded: Operation timeout
	GetStatus(ctx context.Context, runID string) (TestStatus, error)

	// GetLogs retrieves the complete logs from a test run.
	// Returns raw log content as a string. May be empty if logs are not available yet.
	// For large logs, implementations may truncate or paginate results.
	//
	// Common errors:
	//   - ErrTestNotFound: Test run ID doesn't exist or logs expired
	//   - ErrAuthFailed: Authentication credentials are invalid
	GetLogs(ctx context.Context, runID string) (string, error)

	// Cancel attempts to cancel a running test.
	// Returns nil if cancellation was initiated successfully, even if the test is
	// already complete. Implementations should be idempotent.
	//
	// Common errors:
	//   - ErrTestNotFound: Test run ID doesn't exist
	//   - ErrAuthFailed: Authentication credentials are invalid
	Cancel(ctx context.Context, runID string) error
}

type TestStatus string