testreport

type Analysis struct {
	Policy     Policy
	Totals     Totals
	Findings   []Finding
	Suppressed []Suppressed
	// Stale names exemptions that matched packages in this run and
	// suppressed nothing. Reported so a declaration cannot outlive its
	// reason and quietly become an unfalsifiable rule.
	Stale []Exemption
	// Undetermined holds every fact forge could not obtain.
	Undetermined []Unknown
	Malformed    int
}

type Deps struct{}

type Exemption struct {
	// Package matches the Go import path. Accepted spellings: the full
	// import path, a trailing path fragment ("internal/threads" matches
	// "github.com/acme/app/internal/threads"), or either with a "/..."
	// suffix for the subtree.
	Package string `yaml:"package"`
	// Reason is why this package legitimately skips. Required.
	Reason string `yaml:"reason"`
	// MaxSkipRatio is the share this package may skip, in [0,1]. Zero
	// means "fully exempt" (1.0) — a declaration with no number is a
	// blanket one, which is the common case for an integration-only
	// package.
	MaxSkipRatio float64 `yaml:"max_skip_ratio,omitempty"`
}

type Finding struct {
	Package string
	Kind    Kind
	Tests   int
	Skipped int
	Ratio   float64
	// Examples names a few of the skipped tests, shown only when no skip
	// reason could be recovered.
	Examples []string
	// Reasons is the dominant t.Skip message(s) behind the skips, most
	// common first. This is the actionable half of the finding: "124
	// skipped" is a number, `118x "DATABASE_URL not set"` is an instruction.
	Reasons []ReasonCount
	// Detail carries the failure text for [KindFailed].
	Detail string
}

type Kind string

type MockService struct {
	contractkit.Recorder
	ParseFunc   func(io.Reader) (*Run, error)
	AnalyzeFunc func(*Run, Policy) Analysis
	RenderFunc  func(io.Writer, Analysis)
}

type Outcome string

type Package struct {
	Path    string
	Tests   int
	Passed  int
	Failed  int
	Skipped int

	// Skips names the skipped leaf tests, sorted, so a finding can show
	// what actually went missing instead of only a number.
	Skips []string

	// SkipReasons counts the t.Skip messages behind those skips.
	//
	// A list of test NAMES says what went missing; the reason says what to
	// DO about it. "124 tests skipped" is a number to argue with;
	// `118x "DATABASE_URL not set"` is an instruction. cmd/go prints the
	// message as an ordinary output line just before `--- SKIP:`, so it
	// costs nothing to collect — and if the format ever changes the map
	// comes back empty and the report falls back to names, because a
	// verdict must never depend on scraping free text.
	SkipReasons map[string]int

	// Result is the package-level terminal action ("pass"/"fail"/"skip"),
	// or "" when the stream ended before the package finished.
	Result Outcome

	// NoTestFiles is a package cmd/go skipped outright: it has no test
	// files. Not a finding — nothing was lost, there was nothing there.
	NoTestFiles bool

	// BuildFailed is a package that never produced a test binary.
	BuildFailed bool

	// Incomplete is a package with test events but no terminal package
	// event: the stream was truncated (killed run, `head`-ed log, crash).
	// Its tallies are partial, so it is UNDETERMINED rather than counted.
	Incomplete bool
}

type Policy struct {
	// MaxSkipRatio is the share of a package's tests that may skip before
	// the package is reported. See [DefaultPolicy] for the default and
	// the measurement behind it.
	MaxSkipRatio float64
	// MinTests is the sample-size floor for [KindMassSkip]. Below it a
	// ratio is arithmetic, not evidence: 1-of-2 is 50% and means nothing.
	// [KindZeroEvidence] deliberately ignores this floor — "none of them
	// ran" is unambiguous at any size.
	MinTests int
	// Allow holds the declared exemptions.
	Allow []Exemption
}

type ReasonCount struct {
	Reason string
	Count  int
}

type Run struct {
	// Packages, sorted by import path.
	Packages []Package

	// Events is the number of parsed JSON events. Zero means forge learned
	// nothing from this input, which [Analyze] reports as UNDETERMINED.
	Events int

	// Malformed is the number of input lines that were not JSON objects.
	// A few are tolerable (a toolchain banner ahead of the stream); all of
	// them, with zero events, means the input was not `go test -json`.
	Malformed int
}

type Service interface {
	// Parse reads a `go test -json` stream. It returns ErrNoInput when the
	// reader held nothing at all.
	Parse(r io.Reader) (*Run, error)

	// Analyze applies a policy to a parsed run.
	Analyze(run *Run, policy Policy) Analysis

	// Render writes the human-readable report for an analysis.
	Render(w io.Writer, a Analysis)
}

type Status string

type Suppressed struct {
	Package   string
	Kind      Kind
	Tests     int
	Skipped   int
	Ratio     float64
	Exemption Exemption
}

type Totals struct {
	Packages       int // packages that had at least one leaf test
	NoTestFiles    int // packages cmd/go skipped: no test files
	NoTestsRan     int // packages that compiled and ran zero tests (e.g. -run filtered)
	Tests          int
	Passed         int
	Failed         int
	Skipped        int
	SkipRatio      float64
	SuiteFailed    bool
	FailedPackages int
}

type Unknown struct {
	Package string // "" when the whole run is the problem
	Reason  string
}