connector

type Connector interface {
	Name() string
	Ping(ctx context.Context) error
	Extract(ctx context.Context, repo Repo, window Window, sink Sink) Provenance
}

type EndpointStatus struct {
	Accessible bool   `json:"accessible"`
	Reason     string `json:"reason,omitempty"`
}

type Prefetcher interface {
	Prefetch(ctx context.Context, slug string, window Window) error
}

type Provenance struct {
	Connector          string                    `json:"connector"`
	Repo               string                    `json:"repo"`
	WindowCovered      Window                    `json:"window_covered"`
	RowsReturned       map[string]int            `json:"rows_returned"`
	PaginationComplete bool                      `json:"pagination_complete"`
	RateLimitTruncated bool                      `json:"rate_limit_truncated"`
	Errors             map[string]string         `json:"errors"`
	Endpoints          map[string]EndpointStatus `json:"endpoints,omitempty"`
	// Flags carries boolean per-extraction signals the manifest aggregates
	// across repos. Currently used for "mailmap_applied". A flag absent from
	// the map reads as false; the aggregator ANDs across all provenances of
	// the same connector to derive the manifest-wide value.
	Flags map[string]bool `json:"flags,omitempty"`

	// GraphQLPointsUsed is the total number of GraphQL rate-limit points
	// consumed across all requests in this extraction. Zero when no GraphQL
	// calls were made (e.g. REST-only connectors).
	GraphQLPointsUsed int `json:"graphql_points_used,omitempty"`
	// GraphQLPointsRemaining is the remaining GitHub GraphQL rate-limit budget
	// as of the last observed response. Zero when no GraphQL calls were made.
	GraphQLPointsRemaining int `json:"graphql_points_remaining,omitempty"`

	// StreamCancelRetries counts the number of HTTP/2 stream CANCEL frames
	// received from GitHub during this extraction and retried. Non-zero means
	// at least one GraphQL walk hit GitHub's server-side CPU/time budget and
	// had to back off. A successful run with retries > 0 is distinguishable
	// from a clean run; a truncated run also has PaginationComplete = false.
	StreamCancelRetries int `json:"stream_cancel_retries,omitempty"`

	// ConfigDepth records operator-declared extraction-depth overrides that
	// narrow what data was captured. Absent keys mean the connector ran at
	// full depth. The analyser reads this to interpret reduced row counts as
	// "out of scope" rather than "no signal". Currently used by the github
	// connector for "pr_window" and "pr_history_sample".
	ConfigDepth map[string]string `json:"config_depth,omitempty"`

	// Sampling holds per-bucket statistics when sparse-historical PR sampling
	// is active (pr_inflection + pr_history_sample configured). Nil when the
	// connector ran at full PR fidelity. The analyser uses the per-bucket
	// target/actual/total counts to compute confidence intervals on metrics
	// derived from pre-bracket sparse data.
	Sampling *SamplingProvenance `json:"sampling,omitempty"`
}

type Repo struct {
	Slug          string
	DefaultBranch string
	HeadSHA       string
	Team          string
	Clone         string
}

type SampleBucket struct {
	Month     string `json:"month"`               // "2022-01" or "2022-01-W1" for weekly sub-buckets
	Target    int    `json:"target"`              // requested N per bucket
	Actual    int    `json:"actual"`              // PRs emitted
	Total     int    `json:"total"`               // totalCount from GraphQL search
	Truncated bool   `json:"truncated,omitempty"` // true when Total > 1000 (search cap)
}

type SamplingProvenance struct {
	InflectionDate string         `json:"inflection_date"` // "2023-06-01"
	BracketWindow  string         `json:"bracket_window"`  // "12m"
	BracketStart   string         `json:"bracket_start"`   // "2022-06-01"
	BracketEnd     string         `json:"bracket_end"`     // "2026-06-15"
	Strategy       string         `json:"strategy"`        // "search_default_relevance" | "random"
	Buckets        []SampleBucket `json:"buckets"`
}

type Sink interface {
	InsertRepo(model.Repo) error
	InsertTeamRepo(team, repo string) error
	InsertRepoLanguage(model.RepoLanguage) error
	InsertBranch(model.Branch) error
	InsertBranchProtection(model.BranchProtection) error
	InsertCodeowner(model.Codeowner) error

	InsertCommit(model.Commit) error
	InsertCommitFile(model.CommitFile) error
	InsertCommitCoauthor(model.CommitCoauthor) error

	InsertPR(model.PR) error
	InsertPRCommit(model.PRCommit) error
	InsertReview(model.Review) error
	InsertPRComment(model.PRComment) error
	InsertPRReviewRequest(model.PRReviewRequest) error
	InsertPRLabel(model.PRLabel) error

	InsertBuild(model.Build) error
	InsertBuildJob(model.BuildJob) error
	InsertDeploy(model.Deploy) error
	InsertRelease(model.Release) error

	InsertIncident(model.Incident) error
	InsertDefect(model.Defect) error

	InsertFileMetric(model.FileMetric) error
	InsertHarnessArtifact(model.HarnessArtifact) error
	InsertFileComplexityHistory(model.FileComplexityHistory) error
	InsertRepoFile(model.RepoFile) error
}

type Window struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
}