forge

type CheckSummary struct {
	Total, Pending, Success, Failure, Skipped int
	FailedNames, SkippedNames                 []string
}

type Comment struct {
	ID         int64
	Author     string
	AuthorType string
	Body       string
	CreatedAt  time.Time
}

type Commit struct {
	SHA     string
	Subject string
	Body    string
	Author  string
	Date    time.Time // author date
}

type Comparison struct {
	Status         string
	AheadBy        int
	BehindBy       int
	Commits        []Commit // oldest first, as the forge orders them
	Total          int
	Truncated      bool
	Files          []string
	FilesTruncated bool
}

type Fake struct {
	HeadSHAs map[string]string
	// GitTags is what Tags returns; TagsErr, when set, is returned instead.
	GitTags []GitTag
	TagsErr error
	// CreateErr, FindErr and GetErr, when set, are returned by every call to the matching method.
	CreateErr error
	FindErr   error
	GetErr    error
	// ChecksBySHA and ChecksErr configure Checks: a sha not present in the map reports the
	// zero CheckSummary (no checks reported at all), exactly like a real repo with no CI
	// configured; ChecksErr, when set, is returned instead for every call (simulating a 404 or
	// permissions hiccup a caller must retry rather than treat as authoritative absence).
	ChecksBySHA map[string]CheckSummary
	ChecksErr   error
	// CommentsByPR and CommentsErr configure Comments. AddComment is the intended way tests
	// populate CommentsByPR (thread-safe); the field itself may also be set directly before any
	// concurrent use begins.
	CommentsByPR map[int][]Comment
	CommentsErr  error
	// Allowed configures IsAllowedAuthor: logins mapped to true are collaborators with write
	// permission; anything absent is not. AllowedErr, when set, is returned instead — simulating
	// a token missing the scope IsAllowedAuthor needs.
	Allowed    map[string]bool
	AllowedErr error
	// MergeErr, when set, is returned by every call to MergePR regardless of head sha.
	MergeErr error

	// M10 (pkg/migrate) configuration. Refs maps a ref name (tag, branch, full or abbreviated
	// sha) to the full sha ResolveRef answers with; absent means ok=false. Comparisons is keyed
	// "base...head" exactly as a caller would write the range. FilesBySHA feeds CommitFiles;
	// Touching is keyed "ref path" (one space) and feeds CommitsTouching, whose since filter is
	// NOT applied by the fake (the caller is asserting on attribution, not on dates — a test
	// that needs the filter seeds only the shas it expects). Blames is keyed "ref path" and maps
	// line -> LineOrigin. Files is keyed "ref path" and feeds ReadFile. Each *Err, when set, is
	// returned by every call to the matching method.
	Refs        map[string]string
	ResolveErr  error
	Comparisons map[string]Comparison
	CompareErr  error
	FilesBySHA  map[string][]string
	FilesCapped map[string]bool
	FilesErr    error
	Touching    map[string][]string
	TouchingErr error
	Blames      map[string]map[int]LineOrigin
	BlameErr    error
	Files       map[string][]byte
	ReadErr     error

	// Calls records every method invocation, in order, for tests asserting call counts
	// ("CreatePR was called exactly once across both kill/resume attempts").
	Calls []string
	// contains filtered or unexported fields
}

type Forge interface {
	// CreatePR opens a new pull request from spec.Head into spec.Base. The caller (internal/
	// engine's PROpened step) always calls FindPR first — CreatePR is not itself required to
	// deduplicate, though implementations may refuse an obviously duplicate head branch as a
	// safety net (Fake does; the real GitHub API does this on its own, returning 422).
	CreatePR(ctx context.Context, spec PRSpec) (PR, error)
	// FindPR looks for an existing pull request for this promotion: first by headBranch, then
	// — so that a PR survives its branch being renamed or the branch being deleted and
	// recreated — by searching bodyMarker (the exact "<!-- hoist:id=... -->" line) across
	// open PRs and, if that search is empty, recently closed/merged ones within a bound.
	// ok=false means no matching PR exists yet, not an error.
	FindPR(ctx context.Context, headBranch, bodyMarker string) (PR, bool, error)
	// GetPR fetches one pull request by number, ok=false when no such PR exists. It is the
	// exact lookup a caller uses once a promotion has recorded its PR's number (the state file
	// as an index of where to look — AGENTS.md §4.1), in place of FindPR's bounded body-marker
	// scan, which cannot find a merged, branch-deleted PR once enough later PRs have closed
	// past its window (issue #45). The caller still checks the returned PR is its own.
	GetPR(ctx context.Context, number int) (PR, bool, error)
	// Checks reports the check-run rollup for sha. Stubbed/minimal is fine for M3; M4 extends
	// it into a gate.
	Checks(ctx context.Context, sha string) (CheckSummary, error)
	// Comments lists comments on prNumber posted at or after since. Stubbed/minimal is fine
	// for M3; M4 scans these for the approval magic comment.
	Comments(ctx context.Context, prNumber int, since time.Time) ([]Comment, error)
	// IsAllowedAuthor reports whether login is a collaborator with write (or higher) permission
	// on the repo — the second way (besides RepoConfig.Approvers) an Approved comment's author
	// can be accepted (R-001). A permission-scope error (the gh token lacking what this needs)
	// must be returned as an error, never silently folded into false — AGENTS.md §6.1's "the gh
	// token may be missing the repo scope this needs" gotcha applies here exactly as it does to
	// every other adaptor call.
	IsAllowedAuthor(ctx context.Context, login string) (bool, error)
	// MergePR squash-merges prNumber, but only if the PR's current head sha still equals
	// expectedHeadSHA — using the forge's own atomic "merge iff head is X" primitive, never a
	// client-side check-then-merge (a race the caller cannot close on its own). A stale head is
	// reported as an error satisfying errors.Is(err, ErrStaleHead). Merging an already-merged PR
	// is not an error the caller must avoid causing — MergePR may report it either way, and a
	// caller must re-check FindPR before concluding a merge failed outright (a killed process
	// cannot always tell whether its own call landed server-side).
	MergePR(ctx context.Context, prNumber int, expectedHeadSHA string) (PR, error)
	// Tags lists this forge's repo's git tags, each with the date of the commit it points to
	// — bounded, not exhaustive: an adaptor may cap how many it returns rather than crawl an
	// unbounded tag list in full (pkg/forge/github's own Client.Tags stops after
	// maxTagPages*100 = 300 tags today). Added for M6: the tag picker prefers the app repo's
	// own git tags for ordering registry tags by recency (AGENTS.md invariant 3) over the
	// registry's own unordered, timestamp-free tag list (AGENTS.md §6.1 item 3). Order is
	// unspecified — callers sort by Date themselves; a repo with no tags returns an empty
	// slice, not an error.
	Tags(ctx context.Context) ([]GitTag, error)

	// ResolveRef resolves a tag name, branch name, or (possibly abbreviated) commit sha to a
	// full commit sha. ok=false means the forge has no such ref, or the abbreviation is
	// ambiguous — not an error. A scope or permission failure IS an error, never folded into
	// ok=false: pkg/migrate reads ok=false as "try the next source" and an error as "stop", and
	// a token gap read as "unknown" would silently degrade every revision to unresolved
	// (AGENTS.md §6.1 item 1's scope gotcha, at this boundary). M10.
	ResolveRef(ctx context.Context, ref string) (sha string, ok bool, err error)
	// Compare lists the commits and changed files between base and head, three-dot (reachable
	// from head, not from base). Bounded: an adaptor pages up to its own cap and reports
	// Comparison.Truncated rather than crawl further. Either ref unknown to the forge is an
	// error satisfying errors.Is(err, ErrUnknownRef). M10.
	Compare(ctx context.Context, base, head string) (Comparison, error)
	// CommitFiles lists the paths one commit changed, bounded the same way (truncated=true
	// when the forge capped the list). M10.
	CommitFiles(ctx context.Context, sha string) (files []string, truncated bool, err error)
	// CommitsTouching lists, newest first, the shas of commits reachable from ref that changed
	// anything under path (a directory prefix or a file), committed at or after since. Bounded
	// by the adaptor's page cap. M10: how pkg/migrate attributes migration files to the commits
	// that added them without reading every commit in a range.
	CommitsTouching(ctx context.Context, ref, path string, since time.Time) ([]string, error)
	// BlameLines reports, for each requested 1-based line of path at ref, the commit that last
	// changed it. A line past the file's end is absent from the map, not an error. M10: "how
	// long has the image this promotion replaces been live" is the age of the manifest line,
	// not of the file — one file holds several image lines and any one of them moving would
	// reset a file-level date.
	BlameLines(ctx context.Context, ref, path string, lines []int) (map[int]LineOrigin, error)
	// ReadFile returns the content of path at ref. ok=false means the file does not exist
	// there — not an error, since the one caller (pkg/migrate's per-app-repo `.hoist.yaml`)
	// treats absence as "fall back to config". M10.
	ReadFile(ctx context.Context, ref, path string) (content []byte, ok bool, err error)
}

type GitTag struct {
	Name string
	Date time.Time
}

type LineOrigin struct {
	SHA  string
	Date time.Time
}

type PR struct {
	Number     int
	URL        string
	HeadBranch string
	HeadSHA    string
	Base       string
	Merged     bool
	MergeSHA   string
	CreatedAt  time.Time
	// Closed is true for a PR someone closed WITHOUT merging (GitHub's own "state": "closed"
	// with Merged still false) — a dead PR a merge call can never succeed against (a real 405).
	// FindPR's query (state=all, so a renamed-branch/body-marker fallback can still find a
	// promotion's own history) can return one of these, so a caller adopting a found PR must
	// check this explicitly rather than assuming "found" means "usable."
	Closed bool
}

type PRSpec struct {
	Title, Body, Head, Base string
}