provider

type CIEnvMapping struct {
	// ServerURL is the env var that holds the base URL of the forge server
	// (e.g. "CI_SERVER_URL" for GitLab, "GITHUB_SERVER_URL" for GitHub).
	ServerURL string
	// RepoPath is the env var that holds the project path (e.g.
	// "CI_PROJECT_PATH" / "GITHUB_REPOSITORY").
	RepoPath string
	// CommitSHA is the env var that holds the commit SHA (e.g.
	// "CI_COMMIT_SHA" / "GITHUB_SHA").
	CommitSHA string
	// RefName is the env var that holds the analyzed branch or tag name
	// (e.g. "CI_COMMIT_REF_NAME" / "GITHUB_REF_NAME"). It is the
	// authoritative ref in CI, preferred over the resolved default branch.
	RefName string
}

type GitHubProvider struct{}

type GitLabProvider struct{}

type PlatformPolicyLine = control.PlatformPolicyLine

type PlatformPostSummary = control.PlatformPostSummary

type PostActionSummary struct {
	Passed     bool
	GateLine   string
	Score      *control.PlumberScoreResult
	ScoreMode  bool
	ScorePoint bool
	Platform   *PlatformPostSummary
}

type Provider interface {
	// Name returns the canonical provider identifier ("gitlab", "github", …).
	Name() string

	// Controls returns the ordered catalog of controls for this provider.
	// The returned entries drive the compliance table and the per-control
	// rendering sections.
	Controls(pc *configuration.PlumberConfig) []control.ControlEntry

	// ComputeCompliance derives the overall compliance percentage and the
	// number of non-skipped controls that were evaluated from result.
	ComputeCompliance(result *control.AnalysisResult, conf *configuration.Configuration) (compliance float64, controlCount int)

	// Run executes the analysis for this provider using the local clone or
	// the provider's API, depending on conf.
	Run(conf *configuration.Configuration) (*control.AnalysisResult, error)

	// RunRemote fetches the pipeline from a remote API and runs analysis.
	// Returns ErrNoRemote when the provider does not support this mode.
	RunRemote(conf *configuration.Configuration) (*control.AnalysisResult, error)

	// WritePBOM writes a Pipeline Bill of Materials to filePath in the
	// provider's native PBOM format. platform is the platform-mode score
	// block (per-policy verdicts plus the platform's global score), nil on
	// every other run.
	WritePBOM(result *control.AnalysisResult, conf *configuration.Configuration, filePath string, score *control.PlumberScoreResult, scoreMode bool, platform *pbom.PlatformSummary) error

	// WritePBOMCycloneDX writes the PBOM in CycloneDX format.
	WritePBOMCycloneDX(result *control.AnalysisResult, conf *configuration.Configuration, filePath string, score *control.PlumberScoreResult, scoreMode bool, platform *pbom.PlatformSummary) error

	// PostAnalysisActions runs provider-specific post-analysis side-effects
	// such as posting MR comments or updating the project badge. Providers
	// that have no post-analysis actions return nil.
	PostAnalysisActions(cmd *cobra.Command, result *control.AnalysisResult, conf *configuration.Configuration, s PostActionSummary) error

	// BlobURLInfix returns the URL segment between the repository base URL
	// and the file path when building clickable source links.
	// Example: GitLab "/-/blob/", GitHub "/blob/".
	BlobURLInfix() string

	// CIEnvVars returns the mapping of CI environment variables used to
	// build stable source links when running inside a CI pipeline.
	CIEnvVars() CIEnvMapping
}

type StatsBuilder func(controlName string, result *control.AnalysisResult, pc *configuration.PlumberConfig, findings []opaengine.Finding) []control.StatLine