control

type AnalysisResult struct {
	// Project information
	ProjectPath   string `json:"projectPath"`
	ProjectID     int    `json:"projectId"`
	DefaultBranch string `json:"defaultBranch"`
	// AnalyzeBranch is the branch the analysis actually ran against
	// (--branch or the project's default). May differ from DefaultBranch.
	AnalyzeBranch string `json:"analyzeBranch,omitempty"`
	// HeadCommitSha is the head SHA of the analyzed branch, when known.
	// Used to build stable remote source links so that, even if the
	// branch moves later, links in the artifact still point at the
	// exact code that produced the finding. Empty when the SHA could
	// not be resolved (e.g. local-only runs without a fetched HEAD).
	HeadCommitSha string `json:"headCommitSha,omitempty"`

	// CI configuration status
	CiValid        bool     `json:"ciValid"`
	CiMissing      bool     `json:"ciMissing"`
	CiErrors       []string `json:"ciErrors,omitempty"` // Specific CI config errors from GitLab
	CIConfigSource string   `json:"ciConfigSource"`     // "local" or "remote"

	// Pipeline origin data
	PipelineOriginMetrics *PipelineOriginMetricsSummary `json:"pipelineOriginMetrics,omitempty"`

	// Pipeline image data
	PipelineImageMetrics *PipelineImageMetricsSummary `json:"pipelineImageMetrics,omitempty"`

	// Findings from the Rego/OPA rule engine. Single source of truth
	// for compliance results since all legacy Go controls were retired.
	Findings []opaengine.Finding `json:"findings,omitempty"`

	// Raw collected data (not included in JSON output, used for PBOM generation
	// and for the per-control aggregated stats block printed under each
	// control header in the terminal output).
	PipelineImageData  *gitlab.GitlabPipelineImageData      `json:"-"`
	PipelineOriginData *gitlab.GitlabPipelineOriginData     `json:"-"`
	ProtectionData     *gitlab.GitlabProtectionAnalysisData `json:"-"`

	// GitHubStats holds per-control denominators computed from the
	// GitHub IR after a GitHub analysis. Used by the GitHub renderer
	// to produce per-control stats blocks ("Total Images: 19,
	// Pinned By Digest: 1, …") and per-control compliance
	// percentages, matching the GitLab output structure. Nil on the
	// GitLab path.
	GitHubStats *GitHubAnalysisStats `json:"-"`

	// GitHubPipeline is the normalized IR produced by the GitHub
	// collector, retained on the result so legacy JSON / PBOM /
	// CycloneDX builders can read images, action references, and
	// per-branch protection details without re-running the gitlab.
	// Nil on the GitLab path.
	GitHubPipeline *ir.NormalizedPipeline `json:"-"`

	// Warnings holds non-fatal "could not verify" messages from the run,
	// e.g. a known-CVE check skipped because an action's pinned commit
	// could not be resolved to a version (tag list blocked by an org IP
	// allow list, rate limit, or network). Surfaced in the terminal,
	// JSON, SARIF and GLSAST output, and gated by --fail-warnings (exit
	// 3) so a degraded check is visible instead of silently passing.
	Warnings []string `json:"warnings,omitempty"`

	// DataCollectionDegraded is set when a collection or enrichment step
	// failed mid-run, so the analysis ran on incomplete data: a GitLab
	// merged-CI fetch that timed out (empty pipeline), or a GitHub run
	// where some workflow files or the branch-protection fetch could not
	// be retrieved. When true the renderer withholds the letter-score
	// banner and marks the un-collected controls "not evaluated" instead
	// of presenting missing data as 100% compliant (#220). Distinct from
	// CiMissing, which is the legitimate "this project has no CI config"
	// state and is not degraded.
	DataCollectionDegraded bool `json:"dataCollectionDegraded,omitempty"`

	// DegradedReasons lists the human-readable collection/enrichment
	// failures behind DataCollectionDegraded (e.g. "3 workflow file(s)
	// could not be fetched", "branch protection could not be fetched").
	// Surfaced as a caveat in the terminal. Empty when not degraded.
	DegradedReasons []string `json:"degradedReasons,omitempty"`
}

type CodeLoss struct {
	Code         ErrorCode     `json:"code"`
	Severity     IssueSeverity `json:"severity"`
	Count        int           `json:"count"`
	Weight       float64       `json:"weight"`
	Cap          float64       `json:"cap,omitempty"` // omitted when infinite (critical)
	UncappedLoss float64       `json:"uncappedLoss"`
	CappedLoss   float64       `json:"cappedLoss"`
}

type ControlEntry struct {
	DisplayName string
	ControlName string
	Skipped     bool
	// SkipReason is the human-friendly explanation rendered next to
	// the "(skipped)" header and in the Status: SKIPPED (…) line. Left
	// empty for the default "disabled in configuration" case; callers
	// that flip Skipped for a different reason (e.g. a required data
	// source was unavailable) set this so the operator sees why.
	SkipReason string
	Compliance float64
}

type ErrorCode string

type ErrorCodeInfo struct {
	// Code is the unique issue code (e.g., ISSUE-102).
	Code ErrorCode `json:"code"`
	// Severity reflects potential impact (see documentation); used for Plumber Score.
	Severity IssueSeverity `json:"severity"`
	// Title is a short human-readable title used by SARIF / GLSAST / JSON
	// renderers when no provider-specific override is set. Acts as the
	// default; the catalog DisplayName covers the terminal renderer's
	// per-provider naming separately.
	Title string `json:"title"`
	// Description explains what the issue is. Same fallback semantics as
	// Title: rendered as-is when no provider override is set.
	Description string `json:"description"`
	// Remediation provides guidance on how to fix the issue.
	Remediation string `json:"remediation"`
	// DocURL is a direct link to the documentation for this issue.
	DocURL string `json:"docUrl"`
	// ControlName is the .plumber.yaml control key this code belongs to.
	ControlName string `json:"controlName"`

	// TitleByProvider lets cross-provider controls render different titles
	// in SARIF / JSON / GLSAST depending on which provider produced the
	// finding (mirrors the per-provider DisplayName already supported by
	// the catalog). Keyed by "gitlab" / "github". An empty map (the common
	// case) means TitleFor() falls back to Title for every provider.
	TitleByProvider map[string]string `json:"titleByProvider,omitempty"`
	// DescriptionByProvider works the same way for the longer description.
	DescriptionByProvider map[string]string `json:"descriptionByProvider,omitempty"`
}

type GitHubAnalysisStats struct {
	// Actions pinning (ISSUE-701).
	ActionRefsTotal    int
	ActionRefsUnpinned int
	ActionRefsExempt   int

	// Actions supply-chain (ISSUE-702, ISSUE-703, ISSUE-402). Counted
	// across every `uses:` entry that has API metadata, regardless of
	// the pin-by-SHA trusted-owner exemption — the rules themselves do
	// not exempt. In practice trusted-owner refs have nil metadata
	// (enrichment skips them) and won't add to either count.
	ActionRefsArchived   int
	ActionRefsVulnerable int
	ActionRefsAmbiguous  int
	// ActionRefsAbsentUpstream (ISSUE-707) counts SHA-pinned refs the
	// upstream repo confirmed do not exist. Guarded on isShaPinned so it
	// stays aligned with the impostor-commit rego, which only fires on a
	// 40-char SHA.
	ActionRefsAbsentUpstream int

	// Container images (ISSUE-102 / ISSUE-103).
	ImagesTotal          int
	ImagesPinnedByDigest int
	ImagesUsingForbidden int

	// Docker-in-Docker (ISSUE-412 / ISSUE-413).
	JobsTotal              int
	JobsWithDinD           int
	JobsWithInsecureDaemon int

	// Excessive permissions (ISSUE-803). Counts jobs whose effective
	// `permissions:` is the literal `write-all` shortcut (workflow-
	// level grants are propagated per-job by the collector, so the
	// per-job count is the right denominator either way).
	JobsWithWriteAll int

	// Debug trace (ISSUE-203, GitHub side). VariableBindingsTotal is
	// the env-var denominator displayed by the stats block; mirrors
	// the GitLab side's "Variables Checked". DebugTraceFound counts
	// (job, var) pairs where the variable name matches a configured
	// forbidden entry case-insensitively and the value is truthy.
	VariableBindingsTotal int
	DebugTraceFound       int

	// Reusable workflow secrets (ISSUE-302).
	ReusableCalls               int
	ReusableCallsSecretsInherit int

	// Security jobs (ISSUE-410).
	SecurityJobsTotal    int
	SecurityJobsWeakened int

	// Workflow content scanned for template injection (ISSUE-207).
	ScriptLinesTotal int

	// Unverified script execution (ISSUE-411).
	UnverifiedScriptsFound int

	// Workflows + properties (ISSUE-802, ISSUE-801).
	WorkflowsTotal                int
	WorkflowsWithDangerousTrigger int
	WorkflowsMissingPermissions   int

	// Branch protection (ISSUE-501 / ISSUE-505).
	BranchesTotal     int
	BranchesProtected int
	BranchesMatched   int // matched a configured namePattern
	// BranchesProtectionDetailsUnknown counts in-scope branches whose
	// protection-detail fetch did not yield authoritative data
	// (typically: GitHub /branches/{name}/protection 403/404 because
	// the token lacks Administration:Read). The branch_non_compliant
	// rule (ISSUE-505) abstains on such branches; this counter exists
	// so the renderer can surface a "we couldn't fully evaluate this"
	// caveat instead of a misleading 100% compliant.
	BranchesProtectionDetailsUnknown int
}

type IssueSeverity string

type PipelineImageMetricsSummary struct {
	Total uint `json:"total"`
}

type PipelineOriginMetricsSummary struct {
	JobTotal            uint `json:"jobTotal"`
	JobHardcoded        uint `json:"jobHardcoded"`
	OriginTotal         uint `json:"originTotal"`
	OriginComponent     uint `json:"originComponent"`
	OriginLocal         uint `json:"originLocal"`
	OriginProject       uint `json:"originProject"`
	OriginRemote        uint `json:"originRemote"`
	OriginTemplate      uint `json:"originTemplate"`
	OriginGitLabCatalog uint `json:"originGitLabCatalog"`
	OriginOutdated      uint `json:"originOutdated"`
}

type PlumberScoreResult struct {
	ProfileID string `json:"profileId"`

	Counts SeverityCounts `json:"counts"`

	// RawPoints is 100 minus summed capped per-code losses (before Critical malus).
	RawPoints float64 `json:"rawPoints"`
	// FinalPoints applies Critical category malus (max points in E band when any Critical exists).
	FinalPoints float64 `json:"finalPoints"`
	// Score is the letter A–E from final points (what people mean by "how did we score?").
	Score string `json:"score"`

	CriticalMalusApplied bool    `json:"criticalMalusApplied"`
	CriticalMalusMax     float64 `json:"criticalMalusMax,omitempty"` // max points when malus applies (30)

	// Losses is a per-severity rollup of capped per-code losses.
	Losses []SeverityLoss `json:"losses"`
	// CodeLosses is the per-code breakdown that drives the score in scoring-v3.
	CodeLosses []CodeLoss `json:"codeLosses"`
}

type SeverityCounts struct {
	Critical int `json:"critical"`
	High     int `json:"high"`
	Medium   int `json:"medium"`
	Low      int `json:"low"`
}

type SeverityLoss struct {
	Severity   IssueSeverity `json:"severity"`
	Count      int           `json:"count"`
	CappedLoss float64       `json:"cappedLoss"`
}

type StatLine struct {
	Label string
	Value string
}