mutation

package
v1.7.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 10, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package mutation validates and executes exact mutation-testing campaigns.

Index

Constants

View Source 
const (
	// GremlinsVersion is the exact mutation engine release used by the verifier.
	GremlinsVersion = "v0.6.0"
)
View Source 
const (
	// MaximumArchiveSize bounds one imported checkpoint archive.
	MaximumArchiveSize = 16 << 20
)
View Source 
const MaximumMigrationLedgerSize = 4 << 20

MaximumMigrationLedgerSize bounds one approved legacy migration ledger.

Variables

View Source 
var (
	// ErrInvalid identifies malformed mutation evidence or configuration.
	ErrInvalid = errors.New("invalid mutation evidence")
	// ErrUnapproved identifies evidence lacking an exact migration approval.
	ErrUnapproved = errors.New("unapproved mutation evidence migration")
	// ErrInputChanged identifies an otherwise valid checkpoint whose observed
	// package input no longer matches an approved identity.
	ErrInputChanged = errors.New("mutation checkpoint input changed")
)

Functions

func Arguments 

func Arguments(target, output, tags string, discover bool, workers int) ([]string, error)

Arguments returns the complete pinned Gremlins campaign contract.

func InputDigest 

func InputDigest(root string, policy InputPolicy, listing io.Reader, review *ZeroReview) (string, error)

InputDigest binds a mutation campaign to the exact local source, observing tests, fixtures, dependency versions, package policy, and verifier semantics.

func LegacyVerifierDigest 

func LegacyVerifierDigest() string

LegacyVerifierDigest reproduces the current embedded verifier identity.

func SemanticVerifierDigest 

func SemanticVerifierDigest() string

SemanticVerifierDigest is the content identity recorded for native evidence.

func SourceDigest 

func SourceDigest(root, moduleDirectory, packageDirectory string) (string, error)

SourceDigest reproduces the source-only identity used by zero-mutant reviews. It includes direct production Go files and their repository paths.

func VerifierAssets 

func VerifierAssets() map[string][]byte

VerifierAssets returns independent copies of the exact legacy verifier inputs retained for evidence validation and patched verifier builds.

Types

type Campaign 

type Campaign struct {
	Root            string
	EvidenceRoot    string
	MutationRoot    string
	Workspace       string
	Policy          CampaignPolicy
	ZeroReviews     ZeroInventory
	Environment     map[string]string
	RuntimeIdentity RuntimeIdentity
	Process         Process
	Output          io.Writer
	Now             func() time.Time
	// contains filtered or unexported fields
}

Campaign executes or reuses package-granular mutation evidence.

func (Campaign) Import 

func (campaign Campaign) Import(ctx context.Context, checkpoints []Checkpoint, ledger MigrationLedger) error

Import migrates explicitly approved legacy checkpoints to current content-addressed evidence without depending on their Git revisions.

func (Campaign) Run 

func (campaign Campaign) Run(ctx context.Context) error

Run executes missing package campaigns and persists each result immediately.

type CampaignPolicy 

type CampaignPolicy struct {
	Repository        string
	ModuleDirectory   string
	ModulePath        string
	GoVersion         string
	Packages          []string
	TestTags          []string
	BuildTags         []string
	RequiredServices  []string
	ServiceIdentities map[string]string
	OwnedModules      []OwnedModule
	Workers           int
}

CampaignPolicy contains the canonical module and package policy required by mutation execution. Service lifecycle remains owned by the caller.

type Checkpoint 

type Checkpoint struct {
	Module            string
	Package           string
	ExecutionRevision string
	InputDigest       string
	InputLineage      []string
	VerifierDigest    string
	BinaryDigest      string
	VerifierSource    string
	Gremlins          string
	Environment       map[string]string
	ReportDigest      string
	Report            json.RawMessage
	Mutants           int
}

Checkpoint is validated legacy evidence suitable for content-identity migration. Revision fields are intentionally discarded.

func ReadBootstrap 

func ReadBootstrap(reader io.ReaderAt, size int64) ([]Checkpoint, error)

ReadBootstrap strictly reads one bounded legacy checkpoint archive.

type InputMigration 

type InputMigration struct {
	ExecutionRevision      string `json:"execution_revision"`
	GateInputDigest        string `json:"gate_input_digest"`
	ReplacementInputDigest string `json:"replacement_gate_input_digest,omitempty"`
	MigrationReason        string `json:"migration_reason,omitempty"`
	GremlinsVerifierSHA256 string `json:"gremlins_verifier_sha256,omitempty"`
	GremlinsVersion        string `json:"gremlins_version"`
	Module                 string `json:"module"`
	Package                string `json:"package"`
	ReportSHA256           string `json:"report_sha256"`
}

InputMigration approves one exact replacement input identity.

type InputPolicy 

type InputPolicy struct {
	ModuleDirectory   string            `json:"module_directory"`
	PackageDirectory  string            `json:"package_directory"`
	ModulePath        string            `json:"module_path"`
	GoVersion         string            `json:"go_version"`
	TestTags          []string          `json:"test_tags"`
	BuildTags         []string          `json:"build_tags"`
	RequiredServices  []string          `json:"required_services"`
	ServiceIdentities map[string]string `json:"service_identities"`
	OwnedModules      []OwnedModule     `json:"owned_modules"`
}

InputPolicy is the package-level semantic policy bound to mutation evidence.

type MigrationLedger 

type MigrationLedger struct {
	SchemaVersion           int                     `json:"schema_version"`
	Reason                  string                  `json:"reason"`
	VerifierMigrationReview VerifierMigrationReview `json:"verifier_migration_review"`
	VerifierMigrations      []VerifierMigration     `json:"verifier_migrations"`
	Entries                 []InputMigration        `json:"entries"`
}

MigrationLedger binds legacy verifier and input identities to explicitly reviewed semantic replacements. Git revisions are matching data for the old records only; approved evidence emitted by the new tool excludes them.

func ParseMigrationLedger 

func ParseMigrationLedger(reader io.Reader) (MigrationLedger, error)

ParseMigrationLedger strictly parses one bounded approval ledger.

func (MigrationLedger) Approve 

func (ledger MigrationLedger) Approve(checkpoint Checkpoint, currentInput, expectedVerifier string) error

Approve verifies the complete old checkpoint identity and, when necessary, its exact replacement input identity.

type OwnedModule 

type OwnedModule struct {
	ModulePath string `json:"module_path"`
	Directory  string `json:"directory"`
}

OwnedModule identifies a repository-local module whose source may observe a mutation campaign.

type Process 

type Process func(context.Context, string, []string, string, map[string]string, io.Writer, io.Writer) error

Process executes one non-shell command for verifier construction.

type ReportResult 

type ReportResult struct {
	Digest  string
	Mutants int
}

ReportResult summarizes a strictly validated Gremlins report.

func LoadReport 

func LoadReport(root, inputDigest string) ([]byte, ReportResult, error)

LoadReport returns and validates the immutable report for one input digest.

func Reuse 

func Reuse(evidenceRoot, mutationRoot, repository, module, pkg, inputDigest string) (bool, ReportResult, error)

Reuse validates the exact evidence record and report for one package input. Missing evidence is a cache miss; malformed or incomplete evidence fails.

func StoreReport 

func StoreReport(root, inputDigest string, report []byte) (string, bool, ReportResult, error)

StoreReport validates and atomically publishes one immutable report by input. The bool reports whether semantically identical report content already existed.

func ValidateReport 

func ValidateReport(reader io.Reader) (ReportResult, error)

ValidateReport requires every viable mutant to be killed and validates any aggregate counters against the individual mutation records.

type RuntimeIdentity 

type RuntimeIdentity struct {
	GoVersion  string `json:"GOVERSION"`
	GOOS       string `json:"GOOS"`
	GOARCH     string `json:"GOARCH"`
	CGOEnabled string `json:"CGO_ENABLED"`
}

RuntimeIdentity contains only non-secret execution metadata.

func ParseRuntimeIdentity 

func ParseRuntimeIdentity(reader io.Reader) (RuntimeIdentity, error)

ParseRuntimeIdentity validates bounded output from `go env -json`.

type Tool 

type Tool struct {
	Path   string
	Digest string
}

Tool identifies one built, content-addressed verifier binary.

func BuildVerifier 

func BuildVerifier(ctx context.Context, workspace string, process Process) (Tool, error)

BuildVerifier downloads the checksum-pinned Gremlins source, applies the embedded semantic patches, and builds a task-owned binary.

type VerifierMigration 

type VerifierMigration struct {
	ExecutionRevision      string `json:"execution_revision"`
	GateInputDigest        string `json:"gate_input_digest"`
	GremlinsVerifierSHA256 string `json:"gremlins_verifier_sha256"`
	GremlinsVersion        string `json:"gremlins_version"`
	Module                 string `json:"module"`
	Package                string `json:"package"`
	ReportSHA256           string `json:"report_sha256"`
}

VerifierMigration proves which legacy checkpoint used the reviewed verifier.

type VerifierMigrationReview 

type VerifierMigrationReview struct {
	GremlinsVerifierSHA256 string `json:"gremlins_verifier_sha256"`
	Reason                 string `json:"reason"`
	ReviewedAt             string `json:"reviewed_at"`
}

VerifierMigrationReview records the human approval for one verifier.

type ZeroInventory 

type ZeroInventory struct {
	SchemaVersion int          `json:"schema_version"`
	Packages      []ZeroReview `json:"packages"`
}

ZeroInventory contains source- and verifier-bound reviews for packages where the complete mutation operator set finds no viable mutations.

func ParseZeroInventory 

func ParseZeroInventory(reader io.Reader) (ZeroInventory, error)

ParseZeroInventory strictly parses a bounded zero-mutant review inventory.

func (ZeroInventory) Review 

func (inventory ZeroInventory) Review(module, pkg, source, version, verifier string) (*ZeroReview, bool)

Review returns an independent copy of the exact approved zero-mutant review.

func (ZeroInventory) Reviewed 

func (inventory ZeroInventory) Reviewed(module, pkg, source, version, verifier string) bool

Reviewed reports whether an exact source and verifier identity has a human zero-mutant review. Near matches deliberately fail closed.

type ZeroReview 

type ZeroReview struct {
	ModuleDirectory        string `json:"module_directory"`
	PackageDirectory       string `json:"package_directory"`
	SourceDigest           string `json:"source_digest"`
	GremlinsVersion        string `json:"gremlins_version"`
	GremlinsVerifierSHA256 string `json:"gremlins_verifier_sha256"`
	Reason                 string `json:"reason"`
}

ZeroReview explains one exact zero-mutant result.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.