checks

type Category string

type CheckResolver interface {
	// ResolveRef returns the live SHA for owner/repo@ref. ok=false means
	// the resolver could not answer (network failure, unknown ref); checks
	// fail open on that.
	ResolveRef(owner, repo, ref string) (sha string, ok bool)
	// PeelTagObject reports whether a hex SHA names an annotated tag
	// object (or chain of tag-of-tag) and, if so, returns the commit OID
	// it ultimately points at.
	PeelTagObject(ctx context.Context, owner, repo, sha string) (commit string, ok bool)
	// CheckAncestry asks whether candidate is an ancestor of head and
	// returns a short human-readable detail alongside the status — the
	// rate-limit or compare-base detail callers surface to operators — and
	// the API error behind a result GitHub didn't answer (see
	// resolve.Resolver.CheckAncestryCause).
	CheckAncestry(ctx context.Context, owner, repo, candidate, head string) (resolve.AncestryStatus, string, error)
}

type Confidence string

type Deferred struct {
	// Key is the entry's on-disk key (canonical NWO@ref).
	Key string
	// Ref and Commit are what the entry records.
	Ref    string
	Commit string
	// Finding is the finding as it blocks when the entry stays as recorded.
	Finding Finding
	// Restored marks a finding put back on its workflow.
	Restored bool
}

type Finding struct {
	// WorkflowPath is the path to the workflow file.
	WorkflowPath string
	// Category of the finding.
	Category Category
	// Severity of the finding.
	Severity Severity
	// Confidence of the finding — see the Confidence type docs. Always
	// populated at construction; an empty value is a bug and the
	// no-empty-confidence test will catch it.
	Confidence Confidence
	// ActionRef is the action reference this finding relates to (nil for workflow-level findings).
	ActionRef *parserlock.ActionRef
	// Remediable is true for workflow-level findings that pinning can repair.
	Remediable bool
	// Dependency is the existing pinned dep if any.
	Dependency *dep.Dependency
	// ParentNWO is the dep key of the direct action that pulls in this transitive dep (empty if direct).
	ParentNWO string
	// LocalPath is the `./…` value a LocalAction warning names.
	LocalPath string
	// LocalRemoteUses are the remote actions the LocalPath composite uses in
	// the checkout. The runner needs a pin for each, which the lockfile
	// can't record, so the CLI blocks on them.
	LocalRemoteUses []string
	// Detail is a human-readable explanation.
	Detail string
	// Remediation describes what the check command can do about it.
	Remediation string
	// ObservedSHA is the SHA the resolver got at scan time, recorded when
	// it differs from the pinned SHA (e.g. ref-moved, misleading-sha,
	// unreachable-pin).
	ObservedSHA string
	// RecommendedTag is the most recent stable tag whose commit is
	// reachable from a branch, populated for unreachable-SHA findings
	// when one can be found. Empty otherwise.
	RecommendedTag string
	// RecommendedSHA is the commit SHA the recommended tag points to.
	RecommendedSHA string
	// RecommendedSearched is true when the release walk ran for this
	// finding (regardless of outcome). Lets renderers distinguish
	// "we didn't look" from "we looked and found nothing."
	RecommendedSearched bool
	// RefMissing marks a ref-missing or unreachable-pin finding whose ref
	// definitively does not exist upstream. Terminal output titles it
	// separately and skips the release and doc links.
	RefMissing bool
	// RefGone marks an unreachable-pin finding whose checked ref is not a
	// tag or branch, including a full-SHA key's recorded ref, which
	// RefMissing leaves unset. It only picks the terminal title.
	RefGone bool
	// RefRefused marks an unreachable-pin finding whose ref name the Actions
	// backend refuses by policy, so it was never looked up. It only picks
	// the terminal title.
	RefRefused bool
	// TagMoved marks a ref-moved warning from parity: the exact-version tag
	// a full-SHA key records moved ahead of its locked commit. Unlike a
	// sticky mutable ref, the terminal shows it; the JSON category is
	// unchanged.
	TagMoved bool
	// RecordedRef is the lock entry ref a parity finding on a recorded pin
	// checked; empty for a ref this run resolved. FreshRef marks the
	// latter, which the lockfile never recorded.
	RecordedRef string
	FreshRef    bool
	// TermDetail, when set, replaces Detail on the terminal: a short form
	// without request URLs. --json and the run log keep Detail.
	TermDetail string
	// TrackedAction marks a not-pinned bare SHA whose owner/repo the
	// workflow already locks at another ref, or whose entry records its own
	// SHA as its ref. It is a change to a tracked action, not onboarding,
	// so --no-onboard lets it through to be resolved and history-checked.
	TrackedAction bool
	// Reresolve asks planning to drop this finding's recorded dependency
	// from the inventory and resolve it afresh (see PrunesDependency).
	Reresolve bool
	// Retryable marks a check that ended without an answer from GitHub (an
	// outage or rate limit): the entry is unverified, so it blocks until a
	// re-run succeeds. See MarkRetryable.
	Retryable bool
	// RetryReason says why, e.g. "GitHub API unreachable (connection
	// refused)"; RetryAt is the earliest time GitHub said a retry could
	// succeed (zero when it didn't say), and RateLimited marks a rate limit.
	RetryReason string
	RetryAt     time.Time
	RateLimited bool
	// AnonymousLimited marks a rate limit on the anonymous github.com
	// public fallback of a *.ghe.com run, which a tenant token can't raise.
	AnonymousLimited bool
	// ImageUses are the places a container-image finding's image is used.
	ImageUses []uses.Image
}

type InventoryEntry struct {
	Dep    dep.Dependency
	File   string
	Direct bool
	// Parents lists the dep keys of parent composite actions that pull in this
	// transitive dependency. Empty for direct dependencies.
	Parents []string
}

type ParsedWorkflow struct {
	Path string
	// Refs are all remote dependency roots attributed to the workflow. This
	// includes refs found inside in-repo `$/…` actions.
	Refs []parserlock.ActionRef
	// RewriteRefs are the refs that pinning may rewrite in source: the
	// workflow YAML plus the in-repo `$/…` action files it reaches.
	RewriteRefs []parserlock.ActionRef
	// SelfActionFiles are the in-repo action definition files reached through
	// step-level `$/…` refs. They are rewritten alongside the workflow.
	SelfActionFiles []string
	// SelfActionRefs are the remote refs found specifically inside SelfActionFiles.
	SelfActionRefs []parserlock.ActionRef
	// SHASpellings maps each `uses:` value that spells a full SHA in
	// uppercase, as the source has it, to its lowercase form, which Refs
	// carry so lockfile lookups see one spelling.
	SHASpellings map[string]string
	// LocalPaths are the workflow's own `./…` uses.
	LocalPaths []string
	// NestedLocalUses are `./…` uses inside the in-repo `$/…` actions it
	// reaches, with the action that contains each.
	NestedLocalUses    []workflowfile.LocalUse
	SelfRepositoryRefs []string
	// SelfRepositoryRefErrs holds malformed `$/…@ref` values (the invalid form).
	SelfRepositoryRefErrs        []string
	SelfRepositoryResolutionErrs []string
	ExistingDeps                 []dep.Dependency
	// Images are the mutable container images the workflow runs directly.
	Images  []uses.Image
	LoadErr error
	DepsErr error
	// Resolved, when true, instructs DiagnoseParsed to run this
	// workflow's diagnostics with a nil resolver. Network-bound checks
	// (ref-moved) are skipped and the engine relies on
	// purely structural validation against the on-disk lockfile. Caller
	// is asserting "this workflow is already fully resolved" — typically
	// set on the fast path when every direct ref in the workflow is
	// already recorded in the lockfile.
	Resolved bool
}

type PruneEffect int

type Report struct {
	Workflows []WorkflowReport
	// RepoFindings are findings that apply to the repository as a whole
	// (not to any individual workflow).
	RepoFindings []Finding
	// Verified holds the on-disk keys and commits this run resolved afresh
	// and checked with no blocking finding, by VerifiedKey.
	Verified map[string]bool
	// RetriedFor is how long the run waited between retries of requests
	// GitHub didn't answer.
	RetriedFor time.Duration
}

type Severity string

type WorkflowReport struct {
	Path     string
	Findings []Finding
	// SkipCommit prevents terminal parse failures from entering the write phase.
	SkipCommit bool
	// BlockingResolverError indicates that diagnosis classified a resolver error as blocking.
	BlockingResolverError bool
	// ActionRefs are all remote dependency roots attributed to the workflow,
	// including refs found inside in-repo `$/…` actions.
	ActionRefs []parserlock.ActionRef
	// RewriteRefs are the refs eligible for source rewriting: workflow YAML
	// plus the in-repo `$/…` action files listed in SelfActionFiles.
	RewriteRefs []parserlock.ActionRef
	// SHASpellings are the source spellings of uppercase full-SHA refs
	// (see ParsedWorkflow).
	SHASpellings map[string]string
	// SelfActionFiles are in-repo action definition files reached via `$/…`.
	SelfActionFiles []string
	// SelfActionRefs are the remote refs found specifically inside SelfActionFiles.
	SelfActionRefs []parserlock.ActionRef
	// Deps are the existing pinned dependencies (nil if not pinned).
	Deps []dep.Dependency
	// Inventory lists all dependencies with direct/transitive classification.
	Inventory []InventoryEntry
	// Deferred are findings parity excused or accepted on the strength of
	// a write the run has yet to plan.
	Deferred []Deferred
}