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 all per-commit file pages were fetched. It is
	// the precondition for any observed correlation naming this commit.
	Enriched bool `json:"enriched,omitempty"`
	// Files retains fetched pages even when enrichment stops early. When
	// Enriched is false this list is incomplete and cannot prove path absence.
	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 at least 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"`
	// Completion flags distinguish observed absence from evidence not gathered.
	// ChangeSetCollected can be true with Truncated paths; disclosures still apply.
	CommitsCollected   bool `json:"commits_collected"`
	ChangeSetCollected bool `json:"change_set_collected"`
	EstimateOnly       bool `json:"estimate_only"`
	// 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
	// CommitterDate preserves the GitHub committer timestamp when supplied.
	// Date remains the author timestamp for compatibility.
	CommitterDate time.Time `json:"committer_date,omitzero"`
	// WindowDateBasis states which timestamp selected this commit. Omitted
	// when a provider path does not report a verified basis.
	WindowDateBasis string `json:"window_date_basis,omitempty"`
	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 PRActivityEntry struct {
	PR              PullRequest `json:"pr"`
	Matches         []PRMatch   `json:"matches"`
	MatchesComplete bool        `json:"matches_complete"`
}

type PRCostReport struct {
	Consumed          int      `json:"consumed"`
	Ceiling           int      `json:"ceiling"`
	IdentityRequests  int      `json:"identity_requests"`
	DiscoveryRequests int      `json:"discovery_requests"`
	HistoryRequests   int      `json:"history_requests"`
	Quota             *PRQuota `json:"quota,omitempty"`
}

type PRCoverage struct {
	DiscoveryComplete bool `json:"discovery_complete"`
	EvidenceComplete  bool `json:"evidence_complete"`
}

type PRDisclosure struct {
	Kind       string `json:"kind"`
	Reason     string `json:"reason"`
	NextAction string `json:"next_action,omitempty"`
	Repo       string `json:"repo,omitempty"`
	Number     int    `json:"number,omitempty"`
	Stream     string `json:"stream,omitempty"`
}

type PRDraftFilter string

type PRInboxEntry struct {
	PR              PullRequest      `json:"pr"`
	Reasons         []PRRelationship `json:"reasons"`
	ReasonsComplete bool             `json:"reasons_complete"`
}

type PRInboxQuery struct {
	Provider       Provider         `json:"provider"`
	Scope          Scope            `json:"scope"`
	Repos          []string         `json:"repos"`
	Org            string           `json:"org"`
	User           string           `json:"user"`
	IdentitySource string           `json:"identity_source"`
	Relationships  []PRRelationship `json:"relationships"`
	State          PRState          `json:"state"`
	Draft          PRDraftFilter    `json:"draft"`
	MaxPRs         int              `json:"max_prs"`
	MaxRequests    int              `json:"max_requests"`
}

type PRInboxResult struct {
	SchemaVersion string         `json:"schema_version"`
	Workflow      string         `json:"workflow"`
	Provider      Provider       `json:"provider"`
	GeneratedAt   time.Time      `json:"generated_at"`
	Query         PRInboxQuery   `json:"query"`
	PRs           []PRInboxEntry `json:"prs"`
	Count         int            `json:"count"`
	Coverage      PRCoverage     `json:"coverage"`
	Truncated     bool           `json:"truncated"`
	Cost          PRCostReport   `json:"cost"`
	Disclosures   []PRDisclosure `json:"disclosures"`
}

type PRMatch struct {
	ID      string    `json:"id"`
	Kind    string    `json:"kind"`
	At      time.Time `json:"at"`
	Source  string    `json:"source"`
	EventID *int64    `json:"event_id"`
}

type PRQuery struct {
	Provider    Provider      `json:"provider"`
	Scope       Scope         `json:"scope"`
	Repos       []string      `json:"repos"`
	Org         string        `json:"org"`
	Author      string        `json:"author"`
	Role        string        `json:"role"`
	State       PRState       `json:"state"`
	Draft       PRDraftFilter `json:"draft"`
	TimeBasis   PRTimeBasis   `json:"time_basis"`
	Since       time.Time     `json:"since"`
	Until       time.Time     `json:"until"`
	MaxPRs      int           `json:"max_prs"`
	MaxRequests int           `json:"max_requests"`
}

type PRQuota struct {
	Limit     int       `json:"limit"`
	Remaining int       `json:"remaining"`
	Reset     time.Time `json:"reset"`
}

type PRRelationship string

type PRResult struct {
	SchemaVersion string            `json:"schema_version"`
	Workflow      string            `json:"workflow"`
	Provider      Provider          `json:"provider"`
	GeneratedAt   time.Time         `json:"generated_at"`
	Query         PRQuery           `json:"query"`
	PRs           []PRActivityEntry `json:"prs"`
	Count         int               `json:"count"`
	Coverage      PRCoverage        `json:"coverage"`
	Truncated     bool              `json:"truncated"`
	Cost          PRCostReport      `json:"cost"`
	Disclosures   []PRDisclosure    `json:"disclosures"`
}

type PRState string

type PRTimeBasis string

type Provider string

type PullRequest struct {
	Repo               string     `json:"repo"`
	Number             int        `json:"number"`
	URL                string     `json:"url"`
	Title              string     `json:"title"`
	Author             string     `json:"author"`
	State              *PRState   `json:"state"`
	Draft              *bool      `json:"draft"`
	CreatedAt          *time.Time `json:"created_at"`
	UpdatedAt          *time.Time `json:"updated_at"`
	MergedAt           *time.Time `json:"merged_at"`
	ClosedAt           *time.Time `json:"closed_at"`
	Assignees          []string   `json:"assignees"`
	RequestedReviewers []string   `json:"requested_reviewers"`
	RequestedTeams     []string   `json:"requested_teams"`
	BaseRef            *string    `json:"base_ref"`
	HeadRef            *string    `json:"head_ref"`
	Labels             []string   `json:"labels"`
	Milestone          *string    `json:"milestone"`
	Additions          *int       `json:"additions"`
	Deletions          *int       `json:"deletions"`
	ChangedFiles       *int       `json:"changed_files"`
	MissingFields      []string   `json:"missing_fields"`
}

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 are inclusive window bounds. GitHub search and PR
	// discovery use author date; repository/org listings use committer date.
	// Provider filtering is preserved, not emulated by post-filtering an
	// already time-limited listing. 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"`
	// WindowDateBasis is author, committer, or mixed for GitHub discovery.
	// Mixed means repo listings use committer date and open-PR discovery uses
	// author date; each commit records its own basis. Empty means unspecified.
	WindowDateBasis string   `json:"window_date_basis,omitempty"`
	Count           int      `json:"count"`
	Commits         []Commit `json:"commits"`
	// Truncated is true when a cap or later-stage failure made the evidence
	// incomplete.
	Truncated bool `json:"truncated,omitempty"`
	// Cost reports provider requests consumed by the query. Disclosures explain
	// any bound or degradation so a partial result remains auditable in the
	// structured evidence, not only in CLI or MCP error text.
	Cost        CostReport   `json:"cost"`
	Disclosures []Disclosure `json:"disclosures,omitempty"`
	// 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"`
}