pkg

type AdvisoryBlock struct {
	ID           string
	Package      string
	FixedVersion string
	Source       string
}

type BulkUpdateResult struct {
	// Ran is false when the sequence could not complete. FailDetail then
	// explains why, and the model is told to treat the update as NOT done.
	Ran bool
	// FailDetail is empty when Ran is true.
	FailDetail string
	// Output is the tail of the combined command output, for the prompt.
	Output string
}

type BulkUpdater interface {
	Run(ctx context.Context, workdir string) (BulkUpdateResult, error)
}

type ClaudeProber interface {
	// Probe returns nil when claude is authenticated and reachable, or an
	// error describing the failure otherwise.
	Probe(ctx context.Context) error
}

type CreateCommandFunc func(ctx context.Context, repo, episodeSHA string, workflows []string) error

type FixPlanOutput struct {
	Verdict FixVerdict `json:"verdict"`

	// Reason carries the human-readable diagnosis on every path — the
	// reproduction/expected-actual summary the spec writer or escalation
	// message needs.
	Reason string `json:"reason,omitempty"`

	// FailingWorkflows are the workflow names observed red in the task body
	// (or discovered during diagnosis). The spec writer cites them verbatim.
	FailingWorkflows []string `json:"failing_workflows,omitempty"`

	// EpisodeSHA is the CI episode SHA under diagnosis, echoed back for the
	// spec / chain task to pin.
	EpisodeSHA string `json:"episode_sha,omitempty"`
}

type FixResultOutput struct {
	Outcome string `json:"outcome"`
	Message string `json:"message,omitempty"`
	Branch  string `json:"branch,omitempty"`
}

type FixVerdict string

type GateRunner interface {
	// RunTarget runs `make <target>` in workdir. Returns the bounded
	// combined-output tail, the process exit code (0 on success), and a
	// non-nil error when the target failed or could not be started.
	RunTarget(ctx context.Context, workdir, target string) (tail string, exitCode int, err error)

	// RunTargetFull runs `make <target>` in workdir and returns the FULL
	// combined output (no truncation), the process exit code (0 on success),
	// and a non-nil error when the target failed or could not be started.
	// Planning uses this to capture the complete raw scanner output; the
	// bounded RunTarget tail remains for failure messages.
	RunTargetFull(
		ctx context.Context,
		workdir, target string,
	) (output string, exitCode int, err error)
}

type GhCli interface {
	// CreatePR opens a pull request from head against base, running gh
	// inside workdir so the repo is inferred from the git remote. target
	// selects draft or ready-for-review at creation time. label, when
	// non-empty, is added to the PR at creation (e.g. "auto-merge" to opt
	// the PR into GitHub-native auto-merge). Returns the PR URL.
	CreatePR(
		ctx context.Context,
		workdir, base, head, title, body string,
		target PRTarget,
		label string,
	) (string, error)

	// FindOpenPRByHead returns the URL of an open PR whose head is the
	// given branch, or "" when none exists. repo is "owner/name".
	FindOpenPRByHead(ctx context.Context, repo, head string) (string, error)

	// ViewPR returns the state (e.g. "OPEN", "MERGED", "CLOSED") and
	// draft flag of the PR identified by URL.
	ViewPR(ctx context.Context, prURL string) (state string, isDraft bool, err error)

	// FetchFailedLogs returns the failed-step log tail for the latest
	// failing run of the episode SHA on the repo, via `gh run view
	// --log-failed`. Returns "" when no failing run exists for the episode
	// (the caller treats it as "no log evidence"). Used by the build-fix
	// planning step to give the diagnosis LLM concrete failure evidence.
	FetchFailedLogs(ctx context.Context, repo, episodeSHA string) (string, error)
}

type GoBump struct {
	From string `json:"from"`
	To   string `json:"to"`
}

type HardcodedGoVersionPin struct {
	// File is the workflow path relative to the repo root, e.g.
	// ".github/workflows/ci.yml".
	File string
	// Value is the pinned Go version literal, e.g. "1.26.5".
	Value string
}

type InstallationScope interface {
	// Allows reports whether repo ("owner/name") is covered by the token's
	// installation. Unknown means the check itself was impossible — never
	// treat that as denial.
	Allows(ctx context.Context, repo string) ScopeVerdict
}

type ModuleResolver interface {
	// Modules runs `go list -m -f {{.Path}} {{.Version}} all` in workdir under
	// moduleResolveTimeout and returns the parsed module list. A non-nil error
	// means the graph could not be read — the caller fails closed.
	Modules(ctx context.Context, workdir string) ([]ModuleVersion, error)
}

type ModuleVersion struct {
	Path    string
	Version string
}

type PRTarget string

type PRTargets []PRTarget

type PinScanResult struct {
	// PlainPins are single-value `go-version:` pins (hardcoded — the repo's CI
	// toolchain is frozen; a bump desyncs it → escalate).
	PlainPins []HardcodedGoVersionPin
	// MatrixPins are `go-version:` pins inside a strategy matrix (multiple Go
	// versions tested deliberately — NOT a hardcode; no escalation).
	MatrixPins []HardcodedGoVersionPin
}

type PlanOutput struct {
	Outcome string `json:"outcome"`

	// HasWork is true when the execution phase has anything to do.
	// omitempty is deliberately NOT applied so a `false` decision is
	// always written explicitly.
	HasWork bool `json:"has_work"`

	// GoBump records the go-directive bump (from current directive to the
	// image toolchain per design D5). Nil when the directive is already
	// current.
	GoBump *GoBump `json:"go_bump,omitempty"`

	// DepUpdatesExpected is true when `go list -u -m` style inspection
	// found outdated direct dependencies.
	DepUpdatesExpected bool `json:"dep_updates_expected"`

	// GateTargets are the Makefile targets forming the repo's own gate
	// (e.g. precommit, check, vulncheck). Execution and ai_review re-run
	// exactly these to exit 0 — never a hardcoded scanner.
	GateTargets []string `json:"gate_targets,omitempty"`

	// Vulns holds every scanner finding with its fix-vs-park classification.
	Vulns []PlanVuln `json:"vulns,omitempty"`

	// Reason carries the human-readable explanation on the
	// needs_input / no_update_needed paths.
	Reason string `json:"reason,omitempty"`

	// GoUpdateAutoUpdate records the consent flag read from the target
	// repo's .maintainer.yaml at planning entry (mirrors the sibling's
	// ChangelogRewrite). Nil when the planning gate never reached a
	// config read (absent file / fetch error → see ConfigFetchWarning).
	//
	// JSON encoding contract:
	//   - happy path, flag true  → field SET to &true  → JSON emits
	//     literal substring `"go_update_auto_update":true`
	//   - happy path, flag false → field SET to &false → JSON emits
	//     literal substring `"go_update_auto_update":false`
	//   - failure path           → field LEFT nil     → omitempty omits
	//     the token entirely; `go_update_auto_update` is absent from the JSON
	GoUpdateAutoUpdate *bool `json:"go_update_auto_update,omitempty"`

	// ConfigFetchWarning records a non-fatal .maintainer.yaml fetch failure
	// that the planning step recovered from by using the default
	// goUpdate.autoUpdate=false. Populated only when the fetch errored with
	// something OTHER than ErrFileNotFound (transport, DNS, 5xx, timeout).
	// Operators reading the task page can grep this field to confirm
	// whether a repo that opted into updates was silently skipped.
	// Empty on the happy path (file present) and on the legitimate-absent
	// path (404 → ErrFileNotFound).
	ConfigFetchWarning string `json:"config_fetch_warning,omitempty"`

	// ErrorCategory names the failure category on outcome="failed". For
	// the .maintainer.yaml gate the only value is "invalid_config"
	// (goUpdate.autoUpdate is non-boolean or the YAML is malformed).
	// Future failure categories may extend this set.
	ErrorCategory string `json:"error_category,omitempty"`

	// InvalidField names the .maintainer.yaml field that failed validation.
	// Populated on outcome="failed" only; today always "goUpdate.autoUpdate".
	InvalidField string `json:"invalid_field,omitempty"`

	// InvalidValue captures the literal raw value that failed validation
	// (the YAML-decoded string/number/etc., as it appeared in the file).
	// Populated on outcome="failed" only.
	InvalidValue string `json:"invalid_value,omitempty"`
}

type PlanVuln struct {
	// ID is the finding identifier (GO-*, CVE-*, GHSA-*).
	ID string `json:"id"`
	// Package is the vulnerable module path.
	Package string `json:"package,omitempty"`
	// FixedVersion is the patched version the scanner reported; empty when
	// no fix exists (the park case).
	FixedVersion string `json:"fixed_version,omitempty"`
	// Scanner names which gate scanner flagged the finding
	// (govulncheck | osv-scanner | trivy).
	Scanner string `json:"scanner,omitempty"`
	// Action is "fix" (patched version exists — bump it) or "park"
	// (no fix / out-of-scope major — task parks per design D4).
	Action string `json:"action"`
	// Reason is the one-line classification justification.
	Reason string `json:"reason,omitempty"`
}

type ResultOutput struct {
	Outcome string `json:"outcome"`
	Branch  string `json:"branch,omitempty"`
	PRURL   string `json:"pr_url,omitempty"`

	// GateExit is the exit code of the last gate target run (0 = green).
	// omitempty is deliberately NOT applied — an explicit 0 documents the
	// green gate.
	GateExit int `json:"gate_exit"`

	// DepsUpdated counts the module bumps the update sequence applied.
	DepsUpdated int `json:"deps_updated"`

	// VulnsFixed lists the finding IDs resolved by the update — always a
	// subset of the plan's fix-action vulns.
	VulnsFixed []string `json:"vulns_fixed,omitempty"`

	// FailedTarget names the gate target that stayed red (failure path only).
	FailedTarget string `json:"failed_target,omitempty"`

	ErrorCategory git.ErrorCategory `json:"error_category,omitempty"`
	Error         string            `json:"error,omitempty"`
}

type ReviewChecks struct {
	// PROpen — `gh pr view` reports state OPEN.
	PROpen bool `json:"pr_open"`
	// PRDraft — the raw isDraft value reported by `gh pr view`.  The review
	// compares this against the configured PR_TARGET (draft default, ready
	// opt-in); a mismatch is surfaced in the notes and causes approval to
	// fail.  This field always reports what was observed — the match verdict
	// lives in the approval flag and the notes, not here.
	PRDraft bool `json:"pr_draft"`
	// GateGreen — every planned gate target re-ran to exit 0 on a fresh
	// worktree at the branch.
	GateGreen bool `json:"gate_green"`
	// VulnsClear — the scanner-bearing gate targets came back green on the
	// re-run (the gate IS the vuln verdict, per design § 7.3 the repo's
	// gate wraps govulncheck/osv-scanner/trivy).
	VulnsClear bool `json:"vulns_clear"`
	// ChangelogUnreleased — CHANGELOG.md carries a bullet under
	// ## Unreleased and introduces no new version header vs master.
	ChangelogUnreleased bool `json:"changelog_unreleased"`
	// NoNewTag — `git ls-remote --tags` shows no tag pointing at any
	// branch commit.
	NoNewTag bool `json:"no_new_tag"`
}

type ReviewOutput struct {
	Approved bool         `json:"approved"`
	Checks   ReviewChecks `json:"checks"`
	Notes    string       `json:"notes"`
}

type ScannerFinding struct {
	ID           string
	Package      string
	FixedVersion string // empty when the scanner reports no fix
	Scanner      string // govulncheck | osv-scanner | trivy | <target> fallback
}

type ScannerTable []ScannerFinding

type ScopeVerdict string

type UpdateScope string

type UpdateScopes []UpdateScope