quality

type CampaignTestNameKind string

type CampaignTestNameMatch struct {
	File string
	Line int
	Kind CampaignTestNameKind
	Name string
}

type ChangedLines map[string]map[int]bool

type ChangedPackagesResult struct {
	// Target is the branch or ref the caller asked to diff against.
	Target string
	// MergeBase is the resolved merge-base commit of HEAD and Target.
	MergeBase string
	// Packages is the sorted, deduplicated list of `go test`/`go vet`-ready
	// package patterns the diff touches ("." for workingDir's own module
	// root, "./internal/foo" or "../sibling" otherwise, always relative to
	// workingDir). A directory outside the Go module that contains
	// workingDir, a directory belonging to a DIFFERENT Go module nested
	// inside that module (its own go.mod below workingDir's module root —
	// a tools/, examples/, or <product>/backend-style subtree), a directory
	// the diff empties out entirely (fully deleted or moved away), and a
	// directory the go tool itself would never build (no buildable *.go
	// file left in it, a "testdata"/"vendor" directory, or a "_"/"."-prefixed
	// path segment) are never included. A directory whose only *.go files
	// are excluded by build constraints on the current host (an
	// architecture- or OS-specific file that does not match GOOS/GOARCH
	// here) is not detected as such and may still be included — that would
	// need actually loading the build graph, which this function
	// deliberately does not do.
	Packages []string
}

type Check string

type ClockSeamMatch struct {
	// File is the path relative to root, slash-separated.
	File string
	// Line is the match's line number.
	Line int
	// Func is the enclosing function's name (the ClockSeamSite.Func that
	// found it).
	Func string
	// Pattern names which time-package call matched.
	Pattern ClockSeamPattern
}

type ClockSeamPattern string

type ClockSeamSite struct {
	File string
	Func string
}

type CoverageBlock struct {
	File       string
	StartLine  int
	StartCol   int
	EndLine    int
	EndCol     int
	Statements int
	Count      int
}

type CoverageDiagnostic struct {
	Manifest string `yaml:"manifest" json:"manifest"`
	SHA256   string `yaml:"sha256" json:"sha256"`
}

type CoverageDiagnosticFile struct {
	Label         string `yaml:"label" json:"label"`
	Path          string `yaml:"path" json:"path"`
	Bytes         int    `yaml:"bytes" json:"bytes"`
	SHA256        string `yaml:"sha256" json:"sha256"`
	ElapsedNS     int64  `yaml:"elapsed_ns,omitempty" json:"elapsed_ns,omitempty"`
	TimeoutSource string `yaml:"timeout_source,omitempty" json:"timeout_source,omitempty"`
}

type CoverageDiagnosticManifest struct {
	SchemaVersion int    `yaml:"schema_version" json:"schema_version"`
	Repository    string `yaml:"repository" json:"repository"`
	Module        string `yaml:"module" json:"module"`
	// Ambient names the machine-state signals present in the gate's own
	// environment and in the ancestors of TMPDIR and Module when the shard
	// failures below were recorded. Empty when none were observed.
	Ambient envguard.AmbientInputs   `yaml:"ambient,omitempty" json:"ambient,omitempty"`
	Files   []CoverageDiagnosticFile `yaml:"files" json:"files"`
}

type CoverageReport struct {
	SchemaVersion int                  `yaml:"schema_version" json:"schema_version"`
	Repositories  []RepositoryCoverage `yaml:"repositories" json:"repositories"`
	Statements    int                  `yaml:"statements" json:"statements"`
	Covered       int                  `yaml:"covered" json:"covered"`
	Percentage    float64              `yaml:"percentage" json:"percentage"`
}

type CoverageScopeIdentity struct {
	HeadSHA     string `json:"head_sha"`
	BaseSHA     string `json:"base_sha"`
	IncludeE2E  bool   `json:"include_e2e"`
	BuildSHA256 string `json:"build_sha256"`
}

type CoverageScopePackage struct {
	Pattern         string
	ImportPath      string
	Imports         []string
	TestImports     []string
	XTestImports    []string
	EmbedFiles      []string
	TestEmbedFiles  []string
	XTestEmbedFiles []string
}

type CoverageSelection struct {
	Packages        []string               `json:"packages"`
	ChangedPackages []string               `json:"changed_packages"`
	Full            bool                   `json:"full"`
	Reason          string                 `json:"reason"`
	Identity        *CoverageScopeIdentity `json:"identity,omitempty"`
}

type CoverageSummary struct {
	SchemaVersion  int                       `json:"schema_version"`
	Repository     string                    `json:"repository,omitempty"`
	SHA            string                    `json:"sha,omitempty"`
	Ref            string                    `json:"ref,omitempty"`
	WorkflowRunID  int64                     `json:"workflow_run_id,omitempty"`
	WorkflowRunURL string                    `json:"workflow_run_url,omitempty"`
	ReportedAt     time.Time                 `json:"reported_at"`
	Status         Status                    `json:"status"`
	Statements     int                       `json:"statements"`
	Covered        int                       `json:"covered"`
	Percentage     float64                   `json:"percentage"`
	Modules        []ModuleCoverageSummary   `json:"modules,omitempty"`
	Packages       map[string]PackageSummary `json:"packages,omitempty"`
}

type CoverageSummaryMeta struct {
	Repository     string
	SHA            string
	Ref            string
	WorkflowRunID  int64
	WorkflowRunURL string
	ReportedAt     time.Time
	Status         Status
}

type DeadcodeFailureEvidence struct {
	Count      int      `yaml:"count" json:"count"`
	Identities []string `yaml:"identities,omitempty" json:"identities,omitempty"`
	Complete   bool     `yaml:"complete" json:"complete"`
}

type DeadcodeFinding struct {
	// Identity is the baseline key: import path + "." + function name. It
	// deliberately excludes the source position, so moving a function or
	// editing the lines above it does not invalidate the baseline and does not
	// silently re-admit a genuinely new finding.
	Identity string `yaml:"identity" json:"identity"`
	Package  string `yaml:"package" json:"package"`
	Function string `yaml:"function" json:"function"`
	File     string `yaml:"file,omitempty" json:"file,omitempty"`
	Line     int    `yaml:"line,omitempty" json:"line,omitempty"`
}

type DeadcodeOptions struct {
	// Patterns are the main packages to analyze. deadcode only starts from
	// executables, so a pattern matching no main package reports nothing.
	Patterns []string
	// BaselinePath is relative to the repository root when not absolute.
	BaselinePath string
	// Tool overrides the analyzer invocation. When set, the analyzer runs once
	// per Platforms entry, or once with the host environment when Platforms is
	// empty. When nil, the pinned analyzer is installed and run once per
	// platform; Platforms empty then means DefaultDeadcodePlatforms.
	Tool []string
	// Platforms lists the GOOS values to analyse. A function is reported only
	// when it is unreachable on all of them.
	Platforms []string
	// ToolDirectory is the parent directory the analyzer is installed under;
	// empty means the operating system's temporary directory.
	ToolDirectory string
	// Runner starts the analyzer and the go tool; nil uses the real runner.
	Runner runner.Runner
	// GoCommand is the go tool used to install the pinned analyzer; empty
	// means "go".
	GoCommand string
	// Filter is deadcode's -filter regular expression. Empty keeps deadcode's
	// own default, which reports the module of the first listed package.
	Filter string
	// IncludeGenerated reports dead functions in generated files too. Off by
	// default: generated code is not hand-wired, so its reachability is the
	// generator's contract, not this repository's.
	IncludeGenerated bool
	// Timeout bounds the analyzer. Zero disables the bound.
	Timeout time.Duration
}

type DeadcodeReport struct {
	// Platforms lists the GOOS values analysed; Findings, New and Fixed refer
	// to functions unreachable on all of them. Empty when one unscoped run was
	// made with an explicit analyzer.
	Platforms []string `yaml:"platforms,omitempty" json:"platforms,omitempty"`
	// Findings is every unreachable function found, baselined or not.
	Findings []DeadcodeFinding `yaml:"findings" json:"findings"`
	// New is the gate: findings absent from the baseline. Non-empty fails.
	New []DeadcodeFinding `yaml:"new,omitempty" json:"new,omitempty"`
	// Fixed lists baseline entries that are now reachable or gone. They never
	// fail the gate; they are what the baseline should shed.
	Fixed []string `yaml:"fixed,omitempty" json:"fixed,omitempty"`
	// BaselinePath is the file consulted, empty when none was configured.
	BaselinePath string `yaml:"baseline_path,omitempty" json:"baseline_path,omitempty"`
	// BaselineMissing distinguishes "no baseline file yet" from "empty
	// baseline". The first is a repository that has not adopted the gate; the
	// second is a repository that has adopted it and is clean.
	BaselineMissing bool `yaml:"baseline_missing,omitempty" json:"baseline_missing,omitempty"`
}

type ExecSiteMatch struct {
	File    string
	Line    int
	Pattern ExecSitePattern
	Detail  string
}

type ExecSitePattern string

type FileLineOffsets struct {
	// contains filtered or unexported fields
}

type InlineWriteSequenceViolation struct {
	// File is the path relative to root, slash-separated.
	File string
	// Func is the offending function's name, or "ReceiverType.Name" for a
	// method.
	Func string
	// Line is the function declaration's line number, for a human
	// reading the failure to jump straight to it.
	Line int
}

type ModuleCoverage struct {
	Path       string  `yaml:"path" json:"path"`
	Statements int     `yaml:"statements" json:"statements"`
	Covered    int     `yaml:"covered" json:"covered"`
	Percentage float64 `yaml:"percentage" json:"percentage"`
	Attempts   int     `yaml:"attempts,omitempty" json:"attempts,omitempty"`
}

type ModuleCoverageSummary struct {
	Path       string  `json:"path"`
	Statements int     `json:"statements"`
	Covered    int     `json:"covered"`
	Percentage float64 `json:"percentage"`
}

type PackageBaseline struct {
	SchemaVersion   int                         `json:"schema_version"`
	SHA             string                      `json:"sha,omitempty"`
	IncludeE2E      bool                        `json:"include_e2e,omitempty"`
	Packages        map[string]int              `json:"packages"`
	UncoveredBlocks map[string][]UncoveredBlock `json:"uncovered_blocks,omitempty"`
	// RedBase is set when ComputeBaselineAtRef measured a ref whose own
	// tests were failing; see RedBaseline for what that does to the counts.
	RedBase *RedBaseline `json:"red_base,omitempty"`
}

type PackageRatchet struct {
	Package               string
	Uncovered             int
	BaselineUncovered     int
	HasBaseline           bool
	Rose                  bool
	Changed               bool // true when the PR itself touches a file (including _test.go) in this package
	NewlyUncoveredChanged []RatchetFinding
	Pass                  bool
	// Tolerance and Tolerated are set only when the package passed because
	// of its configured RatchetTolerance: Tolerance is the configured
	// statement allowance and Tolerated the statements it let through.
	Tolerance int                  `yaml:"tolerance,omitempty" json:"tolerance,omitempty"`
	Tolerated []ToleratedStatement `yaml:"tolerated,omitempty" json:"tolerated,omitempty"`
}

type PackageSummary struct {
	Statements int     `json:"statements"`
	Covered    int     `json:"covered"`
	Percentage float64 `json:"percentage"`
}

type ParallelBaselineEntry struct {
	Key    string
	Reason string
}

type Progress struct {
	Repository string
	Language   string
	Module     string
	Check      Check
	Command    string
	Detail     string
	State      ProgressState
	Status     Status
	Attempts   int
	Completed  int
	Total      int
}

type ProgressState string

type RatchetFinding struct {
	File   string
	Line   int
	Reason string
}

type RatchetTolerance struct {
	// Statements is how many untouched statements may be newly uncovered
	// against the merge base before the package fails.
	Statements int
	// Reason is the configured justification, repeated in every warning and
	// report entry that uses the tolerance.
	Reason string
	// Functions are the only declarations a tolerated statement may be in.
	Functions []ToleratedFunction
}

type RatchetTolerances map[string]RatchetTolerance

type RatchetWarning struct {
	Package string `json:"package"`
	File    string `json:"file"`
	Line    int    `json:"line"`
	Reason  string `json:"reason"`
}

type RedBaseline struct {
	SHA         string   `yaml:"sha" json:"sha"`
	FailedTests []string `yaml:"failed_tests" json:"failed_tests"`
}

type RepositoryCoverage struct {
	Repository string              `yaml:"repository" json:"repository"`
	Path       string              `yaml:"path" json:"path"`
	Status     Status              `yaml:"status" json:"status"`
	Modules    []ModuleCoverage    `yaml:"modules,omitempty" json:"modules,omitempty"`
	Statements int                 `yaml:"statements" json:"statements"`
	Covered    int                 `yaml:"covered" json:"covered"`
	Percentage float64             `yaml:"percentage" json:"percentage"`
	Error      string              `yaml:"error,omitempty" json:"error,omitempty"`
	Diagnostic *CoverageDiagnostic `yaml:"diagnostic,omitempty" json:"diagnostic,omitempty"`
}

type RunOptions struct {
	Timeout time.Duration
	Retry   int
	// CheckTimeout bounds one logical verification check, including all of its
	// command attempts and any process-isolated Go shards. Zero leaves the
	// existing per-command Timeout behavior unchanged.
	CheckTimeout time.Duration
	// ShardAttemptTimeout bounds one process-isolated Go test shard attempt.
	// Zero retains Timeout as the shard-attempt bound when Timeout is set.
	ShardAttemptTimeout time.Duration
	// GoTestShards runs each explicitly named Go package in this many
	// process-isolated shards. It is opt-in because TestMain and process-global
	// fixtures run once per shard; callers must name packages whose contract
	// permits that isolation. Discovery invokes TestMain once before each shard
	// process invokes it again.
	GoTestShards int
	// GoShardPackages are module-relative package patterns such as
	// ./internal/worktrees. Selected packages not named here still run exactly once.
	GoShardPackages []string
	// GoTestPackages limits coverage to these module-relative Go package
	// patterns. An empty slice retains the default whole-module ./... scope.
	GoTestPackages []string
	// ExplicitGoTestSharding records that the caller selected GoTestShards and
	// GoShardPackages on the command line. Repository policy remains validated
	// and supplies lint commands, but cannot silently broaden this selection.
	ExplicitGoTestSharding bool
	// GoLintCommands replaces the default `go vet ./...` lint step with the
	// repository-owned argv sequences from .wb/quality.yaml. Structured argv
	// keeps exact tool pins reproducible without invoking a shell.
	GoLintCommands [][]string
	// PriorNodeInstallReport permits a later phase over the same repository
	// path to reuse only successful locked Node installs from an earlier phase.
	// A missing or failed install still runs before the later checks.
	PriorNodeInstallReport *VerificationReport
	// CoverageProfile retains the exact merged Go profile for one module.
	// Fleet and multi-module adapters reject it rather than inventing names.
	CoverageProfile string
	// IncludeE2E merges a separately measured native tier into default coverage.
	IncludeE2E bool

	// CoverageDiagnosticsDir retains raw output from failed process-isolated
	// coverage jobs beside the durable coverage report. The human-facing error
	// remains bounded; this private artifact is the lossless recovery path.
	CoverageDiagnosticsDir string
	// CoverageDiagnosticsRepository identifies the owning repository in the
	// private manifest when a fleet runner executes several repositories.
	CoverageDiagnosticsRepository string
	// SingleWorker constrains every check to one worker, so a verification
	// run cannot exceed the workstation's concurrency cap on its own. Go tests
	// gain `-p 1` and never `-race`; package-script Node runs gain
	// `--parallel=1` and `--maxWorkers=1`, while mixed Nx target runs gain
	// only Nx's executor-neutral `--parallel=1`. The Nx daemon and cache are
	// disabled in either case.
	//
	// Serialization is deliberately *not* a substitute for per-file
	// isolation: nothing here relaxes an isolation flag, because a serialized
	// leak is worse than a flake — it is reproducible and misattributed.
	SingleWorker bool
	// Env is appended to each check's environment as KEY=VALUE entries. It is
	// how a caller states the environment a run must carry (GOWORK=off,
	// NX_DAEMON=false) rather than leaving it to the shell that invoked wb.
	Env []string
	// Progress receives lifecycle events for external checks. Callers may use it
	// for terminal diagnostics; reports remain the authoritative output.
	Progress func(Progress)
	// contains filtered or unexported fields
}

type Status string

type ToleratedFunction struct {
	// File is the repository-relative path of the file declaring it.
	File string
	// Name is the declared name, "Func" or "Type.Method".
	Name string
	// StartLine and EndLine bound the declaration in the head file.
	StartLine, EndLine int
}

type ToleratedStatement struct {
	File     string `yaml:"file" json:"file"`
	Line     int    `yaml:"line" json:"line"`
	Function string `yaml:"function" json:"function"`
	Reason   string `yaml:"reason" json:"reason"`
}

type UncoveredBlock struct {
	File      string `json:"file"`
	StartLine int    `json:"start_line"`
	StartCol  int    `json:"start_col"`
	EndLine   int    `json:"end_line"`
	EndCol    int    `json:"end_col"`
}

type UnitTierMatch struct {
	// File is the path relative to root, slash-separated.
	File string
	// Line is the match's line number.
	Line int
	// Pattern names which shape matched.
	Pattern UnitTierPattern
	// Detail is a short human-readable identifier for the match (the
	// selector or identifier name), for a diagnostic message.
	Detail string
	// SelfReexec is set only for UnitTierPatternExecStart: it reports
	// whether the program argument (the exec.Command/os.StartProcess
	// argument that names the executable to run) is exactly the expression
	// os.Args[0] -- Go's own helper-process pattern, re-running the test
	// binary itself, rather than a real external program such as git.
	// TestUnitTierAllowListEntriesAreGenuineHelperProcessReexec (review
	// note #764 B1) requires this on every exec-start match in an
	// allow-listed file.
	SelfReexec bool
}

type UnitTierPattern string

type UnitTierPendingEntry struct {
	File  string
	Count int
	Owner string
}

type ValidationCacheKey struct {
	Repository       string   `json:"repository"`
	TargetRevision   string   `json:"target_revision"`
	Checks           []Check  `json:"checks"`
	QualityConfigSHA string   `json:"quality_config_sha"`
	WBRevision       string   `json:"wb_revision"`
	GoToolchain      string   `json:"go_toolchain"`
	ModuleFiles      []string `json:"module_files"`
	// ValidatorSHAs binds cached evidence to the executable bytes that produced
	// it. In particular, SpecScore's rules can change between installed
	// versions while the repository and WB revision remain identical.
	ValidatorSHAs       map[string]string `json:"validator_shas,omitempty"`
	Timeout             time.Duration     `json:"timeout"`
	Retry               int               `json:"retry"`
	CheckTimeout        time.Duration     `json:"check_timeout"`
	ShardAttemptTimeout time.Duration     `json:"shard_attempt_timeout"`
}

type VerificationEntry struct {
	Language string `yaml:"language" json:"language"`
	Module   string `yaml:"module,omitempty" json:"module,omitempty"`
	Check    Check  `yaml:"check" json:"check"`
	Command  string `yaml:"command,omitempty" json:"command,omitempty"`
	Status   Status `yaml:"status" json:"status"`
	Detail   string `yaml:"detail,omitempty" json:"detail,omitempty"`
	// Deadcode retains complete machine-comparable findings separately from
	// the bounded human diagnostic. A non-nil incomplete value fails closed.
	Deadcode *DeadcodeFailureEvidence `yaml:"deadcode,omitempty" json:"deadcode,omitempty"`
	Attempts int                      `yaml:"attempts,omitempty" json:"attempts,omitempty"`
}

type VerificationReport struct {
	Repository string `yaml:"repository" json:"repository"`
	Path       string `yaml:"path" json:"path"`
	// Revision and WorkspaceClean are populated by the WB command adapter
	// around the complete verification run. They let a downstream receipt bind
	// successful mechanisms to the exact clean Git tree they exercised.
	Revision       string              `yaml:"revision,omitempty" json:"revision,omitempty"`
	WorkspaceClean bool                `yaml:"workspace_clean,omitempty" json:"workspace_clean,omitempty"`
	Status         Status              `yaml:"status" json:"status"`
	Results        []VerificationEntry `yaml:"results" json:"results"`
}

type Worklist struct {
	UnitSize                 int            `json:"unit_size"`
	TotalUncoveredStatements int            `json:"total_uncovered_statements"`
	Units                    []WorklistUnit `json:"units"`
}

type WorklistBlock struct {
	File       string `json:"file"`
	StartLine  int    `json:"start_line"`
	StartCol   int    `json:"start_col"`
	EndLine    int    `json:"end_line"`
	EndCol     int    `json:"end_col"`
	Statements int    `json:"statements"`
	Function   string `json:"function"`
}

type WorklistUnit struct {
	Index          int             `json:"index"`
	Statements     int             `json:"statements"`
	Files          []string        `json:"files"`
	Blocks         []WorklistBlock `json:"blocks"`
	SharesFileWith []int           `json:"shares_file_with,omitempty"`
}