model

type ActivityCommit struct {
	SHA        string `json:"sha"`
	Repo       string `json:"repo"`
	Author     string `json:"author,omitempty"`
	AuthorName string `json:"author_name"`
	Email      string `json:"email,omitempty"`
	URL        string `json:"url"`
	// Message is the full commit message body, not just the summary.
	Message string `json:"message"`
	// AuthorDate is the git author date; CommitterDate is the git committer
	// date. They diverge after a rebase, cherry-pick, or amend, and GitHub
	// bounds the window by the latter.
	AuthorDate    time.Time `json:"author_date"`
	CommitterDate time.Time `json:"committer_date"`
	// ParentSHAs lists the commit's parents; the first element is the first
	// parent, which is what boundary resolution follows.
	ParentSHAs []string `json:"parent_shas,omitempty"`
	// Enriched is true only when per-commit detail was actually fetched. It is
	// the precondition for any observed correlation naming this commit.
	Enriched bool `json:"enriched,omitempty"`
	// Files is populated only when Enriched.
	Files []File `json:"files,omitempty"`
}

type ActivityQuery struct {
	// Provider is the source control provider. Only ProviderGitHub is
	// supported; anything else is rejected at resolve time.
	Provider Provider
	// Repo is the "owner/name" target.
	Repo string
	// Ref is the branch or tag to examine. Empty means the repository's
	// default branch.
	Ref string
	// Since and Until bound the window, normalized to UTC.
	Since time.Time
	Until time.Time
	// Author optionally narrows the commit listing. The change set is not
	// author-filtered — a boundary comparison has no notion of authorship —
	// and a disclosure says so whenever both are present.
	Author string
	// IncludeDiffs requests bounded patch text in the change set.
	IncludeDiffs bool
	// MaxDiffBytes caps patch text; 0 uses DefaultMaxDiffBytes.
	MaxDiffBytes int
	// EnrichCommits is the size of the opt-in per-commit detail subset. It
	// costs one request per commit and is what enables observed (rather than
	// inferred) path attribution. 0 disables enrichment.
	EnrichCommits int
	// MaxRequests caps the provider requests this query may consume. 0
	// disables the ceiling; it defaults to DefaultMaxRequests.
	MaxRequests int
	// EstimateOnly reports projected cost and stops, gathering no evidence.
	EstimateOnly bool
}

type ActivityResult struct {
	// SchemaVersion pins the ActivityResult contract; it is always
	// ActivitySchemaVersion and never the zero value.
	SchemaVersion string    `json:"schema_version"`
	GeneratedAt   time.Time `json:"generated_at"`
	Provider      Provider  `json:"provider"`
	Repo          string    `json:"repo"`
	// Ref is the reference actually compared, never empty in output.
	Ref   string    `json:"ref"`
	Since time.Time `json:"since"`
	Until time.Time `json:"until"`
	// WindowDateBasis names which commit date bounded the window: "committer"
	// or "author". GitHub filters on the committer date.
	WindowDateBasis string           `json:"window_date_basis"`
	Boundaries      Boundaries       `json:"boundaries"`
	Count           int              `json:"count"`
	Commits         []ActivityCommit `json:"commits"`
	ChangeSet       ChangeSet        `json:"change_set"`
	Correlations    []Correlation    `json:"correlations,omitempty"`
	// Cost is always populated, including on every early-return path: a query
	// that stopped early must still report what it spent.
	Cost CostReport `json:"cost"`
	// Disclosures record everything that bounded or degraded the result, plus
	// the two unconditional blind-spot statements that accompany any change
	// set.
	Disclosures []Disclosure `json:"disclosures,omitempty"`
}

type Boundaries struct {
	// BaseSHA is the parent of the earliest in-window commit. Empty when the
	// earliest in-window commit is the repository root.
	BaseSHA string `json:"base_sha"`
	// HeadSHA is the latest in-window commit.
	HeadSHA string `json:"head_sha"`
	// BaseSource records how the base was chosen: BaseSourceParentOfEarliest
	// or BaseSourceRepositoryRoot. Resolution is by ancestry, never by
	// timestamp proximity.
	BaseSource string `json:"base_source"`
	// Status is the provider's comparison status: ahead, identical, diverged,
	// or behind.
	Status string `json:"status"`
	// SharedRoot is false when the boundaries do not share ancestry, in which
	// case the change set is suppressed rather than rendered.
	SharedRoot bool `json:"shared_ancestry"`
}

type ChangeSet struct {
	// Paths is sorted lexicographically so identical upstream state yields
	// byte-identical output; provider ordering is not guaranteed stable.
	Paths          []ChangedPath `json:"paths"`
	TotalAdditions int           `json:"total_additions"`
	TotalDeletions int           `json:"total_deletions"`
	// Truncated is true when the provider's file cap clipped the comparison.
	Truncated bool `json:"truncated,omitempty"`
}

type ChangedPath struct {
	Path           string `json:"path"`
	PreviousPath   string `json:"previous_path,omitempty"`
	Status         string `json:"status"`
	Additions      int    `json:"additions"`
	Deletions      int    `json:"deletions"`
	Patch          string `json:"patch,omitempty"`
	PatchTruncated bool   `json:"patch_truncated,omitempty"`
}

type Commit struct {
	SHA        string    `json:"sha"`
	Repo       string    `json:"repo"`             // "owner/repo"
	Author     string    `json:"author,omitempty"` // GitHub login, if known
	AuthorName string    `json:"author_name"`      // git author name
	Email      string    `json:"email,omitempty"`  // git author email
	Date       time.Time `json:"date"`             // git author date
	Message    string    `json:"message"`          // full commit message
	URL        string    `json:"url"`              // html_url
	// Source records how the commit was discovered so a match is auditable:
	// "search" (commit search index), "repo" (default-branch listing), or
	// "pull/<n>" (open pull-request branch). Empty for provider paths that do
	// not tag a source (e.g. GitLab).
	Source    string `json:"source,omitempty"`
	Additions int    `json:"additions,omitempty"`
	Deletions int    `json:"deletions,omitempty"`
	Changes   int    `json:"changes,omitempty"`
	Files     []File `json:"files,omitempty"`
}

type Correlation struct {
	Path string `json:"path"`
	// SHAs is sorted; empty means the path is unattributed.
	SHAs []string `json:"shas,omitempty"`
	// Basis is BasisObserved or BasisInferred.
	Basis string `json:"basis"`
	// Rule names the rule that produced an inferred basis.
	Rule string `json:"rule,omitempty"`
}

type CostReport struct {
	// Estimated is the projected request count; 0 when no estimate was run.
	Estimated int `json:"estimated"`
	Consumed  int `json:"consumed"`
	// Ceiling is the configured request cap; 0 means disabled.
	Ceiling        int       `json:"ceiling"`
	QuotaRemaining int       `json:"quota_remaining"`
	QuotaLimit     int       `json:"quota_limit"`
	QuotaResetsAt  time.Time `json:"quota_resets_at,omitempty"`
}

type Disclosure struct {
	Kind       string `json:"kind"`
	Reason     string `json:"reason"`
	NextAction string `json:"next_action,omitempty"`
}

type File struct {
	Path           string `json:"path"`
	PreviousPath   string `json:"previous_path,omitempty"`
	Status         string `json:"status,omitempty"`
	Additions      int    `json:"additions,omitempty"`
	Deletions      int    `json:"deletions,omitempty"`
	Changes        int    `json:"changes,omitempty"`
	Patch          string `json:"patch,omitempty"`
	PatchTruncated bool   `json:"patch_truncated,omitempty"`
}

type Provider string

type Query struct {
	// Provider is the source control provider to query.
	Provider Provider
	// Author is the provider author identifier whose commits are wanted. For
	// GitHub this is a login or an email; in the search scope an email is
	// matched with the author-email: qualifier and a login with author:. For
	// GitLab this is matched against the commit author string.
	Author string
	// Since and Until bound the commit author date, inclusive. A zero Until
	// means "now".
	Since time.Time
	Until time.Time
	// Scope selects the discovery strategy.
	Scope Scope
	// Repos is the list of "owner/repo" targets for ScopeRepos.
	Repos []string
	// Org is the organization login for ScopeOrg.
	Org string
	// IncludeStats requests per-commit additions/deletions. This costs one
	// extra API call per commit, so it is off by default.
	IncludeStats bool
	// IncludeFiles requests per-file change summaries. Providers usually fetch
	// this from the same detail endpoint as stats.
	IncludeFiles bool
	// IncludeDiffs requests patch text for changed files. This implies
	// IncludeFiles and is bounded by MaxDiffBytes.
	IncludeDiffs bool
	// MaxDiffBytes caps patch text per commit when IncludeDiffs is true.
	MaxDiffBytes int
	// MaxCommits caps the number of commits returned (0 = no cap).
	MaxCommits int
	// IncludePullRequests augments repos/org discovery with commits found on
	// open pull-request branches. These commits are not yet on a default branch,
	// so commit search and branch listing miss them; enabling this enumerates
	// open PRs per repo and merges author-matching commits as evidence. It costs
	// extra API calls (one PR list + one commit list per PR), so it is off by
	// default. GitHub only; ignored for GitLab.
	IncludePullRequests bool
	// MaxRequests caps the provider API requests this query may consume
	// (0 = no cap). Reaching the cap yields the partial results gathered so far
	// rather than an abort.
	//
	// Query is a request type, not part of the serialized evidence contract, so
	// adding a field here does not bump SchemaVersion.
	MaxRequests int
}

type Result struct {
	// SchemaVersion pins the Result contract (see the package SchemaVersion
	// constant). GeneratedAt records when the query ran, giving the result
	// evidence-style provenance.
	SchemaVersion string    `json:"schema_version"`
	GeneratedAt   time.Time `json:"generated_at"`
	Provider      Provider  `json:"provider,omitempty"`
	Author        string    `json:"author"`
	Scope         Scope     `json:"scope"`
	Since         time.Time `json:"since"`
	Until         time.Time `json:"until"`
	Count         int       `json:"count"`
	Commits       []Commit  `json:"commits"`
	Truncated     bool      `json:"truncated,omitempty"` // true if MaxCommits clipped results
	// Skipped lists repositories an org-scope scan could not list and skipped so
	// that one bad repo (e.g. an empty repo, or one the token cannot read) does
	// not abort the whole scan. Empty/omitted when nothing was skipped.
	Skipped []SkippedRepo `json:"skipped,omitempty"`
}

type Scope string

type SkippedRepo struct {
	Repo   string `json:"repo"`
	Reason string `json:"reason"`
}