goverify

Documentation

Overview

Package goverify discovers and verifies bounded Go repository material

Index

• Constants
• Variables
• func CheckModuleCurrency(ctx context.Context, root string, tool Tool, module Module) error
• func CompileModule(ctx context.Context, root string, tool Tool, module Module, output io.Writer) (err error)
• func CoverageText(value Coverage) string
• func Fix(tool Tool, directory string, packages ...string) verify.Control
• func Format(tool Tool, directory string, arguments ...string) verify.Control
• func Lint(tool Tool, directory string, arguments ...string) verify.Control
• func ModuleTidy(tool Tool, directory string) verify.Control
• func ModuleVerify(tool Tool, directory string) verify.Control
• func Race(tool Tool, directory string, packages ...string) verify.Control
• func ReplaceEnvironment(environment []string, name, value string) []string
• func RepositoryPlanFor(ctx context.Context, root string, repository Repository, profileID string) (verify.Plan, error)
• func ResolveRepositoryTool(ctx context.Context, root string, modules []RepositoryModule, ...) (string, error)
• func RunBenchmarks(ctx context.Context, root string, tool Tool, targets []BenchmarkTarget, ...) error
• func RunCoverage(ctx context.Context, root string, tool Tool, scope TestScope, output io.Writer) (err error)
• func RunFuzzCampaign(ctx context.Context, root string, campaign Campaign, targets []FuzzTarget, ...) error
• func Test(tool Tool, directory string, packages ...string) verify.Control
• func Toolchain(tool Tool, directory, version string) verify.Control
• func VerifyWorkflowCurrency(ctx context.Context, root string, paths []string, git Tool) error
• func VerifyWorkflowReferences(ctx context.Context, root string, paths []string) (err error)
• func Vet(tool Tool, directory string, packages ...string) verify.Control
• func Vulnerabilities(tool Tool, directory string, packages ...string) verify.Control
• func WriteFuzzInventory(ctx context.Context, targets []FuzzTarget, output io.Writer) error
• type BenchmarkTarget
• type Campaign
• type Compatibility
• type Coverage
  • func CheckCoverage(reader io.Reader) (Coverage, error)
• type FuzzModule
• type FuzzTarget
  • func DiscoverFuzzTargets(ctx context.Context, root string, tool Tool, modules []FuzzModule) (targets []FuzzTarget, err error)
• type Module
• type Repository
  • func RepositoryFromModules(modules []RepositoryModule, base Repository) (Repository, error)
• type RepositoryInventory
  • func DiscoverRepository(ctx context.Context, root string, tool Tool) (RepositoryInventory, error)
• type RepositoryModule
• type TestScope
• type TestTarget
• type TestTargets
  • func DiscoverTestTargets(ctx context.Context, root string, tool Tool, modules []FuzzModule) (targets TestTargets, err error)
• type Tool
• type WorkflowReference
  • func InspectWorkflowReferences(source []byte) ([]WorkflowReference, error)
• type WorkflowReferenceKind

Constants

const MaxCoverageBytes = 64 << 20

const MaxCoverageLineBytes = 64 << 10

const MaxCoverageRows = MaxCoverageBytes / minimumCoverageRowBytes

const MaxFuzzDiagnosticBytes = 4 << 10

const MaxFuzzEntries = 100_000

const MaxFuzzExecutions = 1_000_000_000

const MaxFuzzJobs = 32

const MaxFuzzModules = 16

const MaxFuzzParallelism = 256

const MaxFuzzPathBytes = 4 << 10

const MaxFuzzSourceBytes = maxSourceBytes

const MaxFuzzTargets = 1 << 10

const MaxFuzzTotalBytes = 64 << 20

const MaxFuzzWorkBytes = 64

const MaxLocalActionBytes = 16 << 20

const MaxLocalActions = MaxRepositorySources

const MaxRepositoryCommandBytes = 1 << 20

const MaxRepositoryEntries = 100_000

const MaxRepositoryModules = verify.MaxProfiles / 2

const MaxRepositorySourceBytes = verify.MaxArgumentBytes - verify.MaxPathBytes

const MaxRepositorySources = verify.MaxArguments - 2

const MaxWorkflowBytes = 64 << 10

const MaxWorkflowDepth = 100

const MaxWorkflowLineBytes = 4 << 10

const MaxWorkflowNodes = MaxWorkflowBytes

const MaxWorkflowParserDepth = 10_000

const MaxWorkflowPathComponents = 64

const MaxWorkflowReferences = 4 << 10

Variables

var ErrBenchmarkInventory = errors.New("invalid Go benchmark inventory")

var ErrCoverageProfile = errors.New("invalid Go coverage profile")

var ErrDependencyCurrency = errors.New("go dependency update available")

var ErrFuzzCampaign = errors.New("go fuzz campaign failed")

var ErrFuzzInventory = errors.New("invalid Go fuzz inventory")

var ErrIncompleteCoverage = errors.New("go statement coverage is incomplete")

var ErrRepositoryDiscovery = errors.New("invalid Go repository inventory")

var ErrWorkflowCurrency = errors.New("workflow dependency update available")

var ErrWorkflowReferences = errors.New("invalid workflow execution reference")

Functions

func CheckModuleCurrency

func CheckModuleCurrency(ctx context.Context, root string, tool Tool, module Module) error

CheckModuleCurrency requires the selected module dependency graph to have no applicable update

func CompileModule

func CompileModule(ctx context.Context, root string, tool Tool, module Module, output io.Writer) (err error)

CompileModule compiles tests to the platform null device without executing or retaining binaries

func CoverageText

func CoverageText(value Coverage) string

CoverageText renders a concise complete-coverage result

func Fix

func Fix(tool Tool, directory string, packages ...string) verify.Control

Fix constructs a non-mutating go fix control

func Format

func Format(tool Tool, directory string, arguments ...string) verify.Control

Format constructs a non-mutating GolangCI-Lint formatting control

func Lint

func Lint(tool Tool, directory string, arguments ...string) verify.Control

Lint constructs a GolangCI-Lint control

func ModuleTidy

func ModuleTidy(tool Tool, directory string) verify.Control

ModuleTidy constructs a non-mutating module tidiness control

func ModuleVerify

func ModuleVerify(tool Tool, directory string) verify.Control

ModuleVerify constructs an exact module-integrity control

func Race

func Race(tool Tool, directory string, packages ...string) verify.Control

Race constructs a shuffled uncached race-detector control

func ReplaceEnvironment

func ReplaceEnvironment(environment []string, name, value string) []string

ReplaceEnvironment returns an owned environment with one case-insensitive name replacement

func RepositoryPlanFor

func RepositoryPlanFor(ctx context.Context, root string, repository Repository, profileID string) (verify.Plan, error)

RepositoryPlanFor constructs and validates one selected repository profile

func ResolveRepositoryTool

func ResolveRepositoryTool(ctx context.Context, root string, modules []RepositoryModule, modulePath string, tool Tool) (string, error)

ResolveRepositoryTool resolves one uniquely declared Go tool executable

func RunBenchmarks

func RunBenchmarks(ctx context.Context, root string, tool Tool, targets []BenchmarkTarget, output io.Writer) error

RunBenchmarks executes exact grouped targets and requires one result for each declaration

func RunCoverage

func RunCoverage(ctx context.Context, root string, tool Tool, scope TestScope, output io.Writer) (err error)

RunCoverage executes one test scope and requires complete atomic statement coverage

func RunFuzzCampaign

func RunFuzzCampaign(ctx context.Context, root string, campaign Campaign, targets []FuzzTarget, output io.Writer) error

RunFuzzCampaign executes every exact target under one aggregate owner

func Test

func Test(tool Tool, directory string, packages ...string) verify.Control

Test constructs a shuffled uncached Go test control

func Toolchain

func Toolchain(tool Tool, directory, version string) verify.Control

Toolchain constructs an exact Go version control

func VerifyWorkflowCurrency

func VerifyWorkflowCurrency(ctx context.Context, root string, paths []string, git Tool) error

VerifyWorkflowCurrency requires every remote action pin to use the highest compatible stable tag

func VerifyWorkflowReferences

func VerifyWorkflowReferences(ctx context.Context, root string, paths []string) (err error)

VerifyWorkflowReferences requires bounded immutable workflow and local-action references

func Vet

func Vet(tool Tool, directory string, packages ...string) verify.Control

Vet constructs a go vet control

func Vulnerabilities

func Vulnerabilities(tool Tool, directory string, packages ...string) verify.Control

Vulnerabilities constructs a Govulncheck control

func WriteFuzzInventory

func WriteFuzzInventory(ctx context.Context, targets []FuzzTarget, output io.Writer) error

WriteFuzzInventory writes the exact ordered candidate inventory

Types

type BenchmarkTarget

type BenchmarkTarget = TestTarget

BenchmarkTarget identifies one benchmark candidate whose signature remains compiler-owned

type Campaign

type Campaign struct {
	Go          Tool          // Go executes every target
	Duration    string        // Duration is a Go fuzz duration or canonical Nx execution count
	Parallelism int           // Parallelism is passed to each Go fuzz process
	Jobs        int           // Jobs is the campaign worker count; zero selects one
	Timeout     time.Duration // Timeout bounds the complete campaign; zero derives it from per-target bounds
}

Campaign defines complete fuzz work across an exact target inventory

type Compatibility

type Compatibility struct {
	Version string   // Version is an exact Go toolchain version
	Scopes  []string // Scopes names TestScope values; empty selects every scope
}

Compatibility describes one Go toolchain and its admitted test scopes

type Coverage

type Coverage struct {
	Rows       int    // Rows is the parsed source-range count
	Statements uint64 // Statements is the declared statement count
	Covered    uint64 // Covered is the statement count with non-zero execution
}

Coverage summarises one complete atomic Go coverage profile

func CheckCoverage

func CheckCoverage(reader io.Reader) (Coverage, error)

CheckCoverage requires a bounded complete atomic coverage profile

type FuzzModule

type FuzzModule struct {
	Directory string // Directory is repository-relative; dot selects the root
	Path      string // Path is the declared module path
}

FuzzModule binds one module path to its repository directory

type FuzzTarget

type FuzzTarget = TestTarget

FuzzTarget identifies one fuzz candidate whose signature remains compiler-owned

func DiscoverFuzzTargets

func DiscoverFuzzTargets(ctx context.Context, root string, tool Tool, modules []FuzzModule) (targets []FuzzTarget, err error)

DiscoverFuzzTargets inventories source candidates without executing repository code

type Module

type Module struct {
	Directory  string   // Directory is repository-relative; empty selects the root
	Name       string   // Name is printable output ownership
	Packages   []string // Packages is the ordered package argument set
	Tools      []string // Tools is the ordered tool package set
	Production bool     // Production includes indirect dependency currency checks
}

Module describes one admitted Go module

type Repository

type Repository struct {
	ID                 string           // ID is the lowercase plan identity
	Self               string           // Self is the absolute secverify executable used by internal controls
	Go                 Tool             // Go executes module, test, coverage, compile and fuzz work
	Linter             Tool             // Linter executes formatting and static analysis
	Vulnerability      Tool             // Vulnerability executes dependency vulnerability analysis
	ExactGo            string           // ExactGo is the required primary Go version
	LinterConfig       string           // LinterConfig is the root configuration path
	Modules            []Module         // Modules is the ordered module inventory
	TestScopes         []TestScope      // TestScopes is the ordered test ownership inventory
	FuzzModules        []FuzzModule     // FuzzModules bounds source target discovery
	Fuzz               Campaign         // Fuzz defines campaign work and ownership
	Compatibility      []Compatibility  // Compatibility lists older toolchains to exercise
	ExtraStatic        []verify.Control // ExtraStatic follows built-in static controls
	ExtraTest          []verify.Control // ExtraTest follows built-in test controls
	AdditionalProfiles []verify.Profile // AdditionalProfiles are selected only by their own identity
}

Repository contains the exact material used to construct a verification plan

func RepositoryFromModules

func RepositoryFromModules(modules []RepositoryModule, base Repository) (Repository, error)

RepositoryFromModules constructs repository ownership from a validated module inventory

type RepositoryInventory

type RepositoryInventory struct {
	Modules       []RepositoryModule // Modules follows repository traversal order
	LinterConfig  string             // LinterConfig is the unique root GolangCI-Lint file
	ShellFiles    []string           // ShellFiles is the ordered .sh inventory
	WorkflowFiles []string           // WorkflowFiles is the ordered GitHub workflow inventory
}

RepositoryInventory is the complete bounded discovery result

func DiscoverRepository

func DiscoverRepository(ctx context.Context, root string, tool Tool) (RepositoryInventory, error)

DiscoverRepository inventories an absolute repository root without following symlinks

type RepositoryModule

type RepositoryModule struct {
	Directory     string   // Directory is repository-relative; dot selects the root
	Path          string   // Path is the declared module path
	GoVersion     string   // GoVersion is the language version without the go prefix
	Toolchain     string   // Toolchain is the declared toolchain or nested preference
	Tools         []string // Tools is the ordered tool directive inventory
	HasPackages   bool     // HasPackages reports at least one owned Go source file
	HasProduction bool     // HasProduction reports at least one non-test Go source file
}

RepositoryModule is one discovered module before plan construction

type TestScope

type TestScope struct {
	Directory    string   // Directory is repository-relative; empty selects the root
	Name         string   // Name is printable output ownership
	Packages     []string // Packages is the ordered package argument set
	SkipCoverage bool     // SkipCoverage omits coverage while retaining race verification
}

TestScope describes one package set tested and covered together

type TestTarget

type TestTarget struct {
	Module    string // Module is the owning module path
	Package   string // Package is the complete package import path
	Name      string // Name is the source declaration name
	Directory string // Directory is the owning module directory
	Argument  string // Argument is the package argument relative to Directory
}

TestTarget identifies one source-declared fuzz target or benchmark candidate

type TestTargets

type TestTargets struct {
	Fuzz       []FuzzTarget      // Fuzz contains source-declared fuzz candidates
	Benchmarks []BenchmarkTarget // Benchmarks contains source-declared benchmark candidates
}

TestTargets contains the complete ordered source target inventory

func DiscoverTestTargets

func DiscoverTestTargets(ctx context.Context, root string, tool Tool, modules []FuzzModule) (targets TestTargets, err error)

DiscoverTestTargets inventories fuzz and benchmark source candidates

type Tool

type Tool struct {
	Executable  string        // Executable is an absolute regular file or a symlink to one
	Environment []string      // Environment is the complete child environment
	Timeout     time.Duration // Timeout bounds process execution before process-tree cleanup begins
	OutputLimit int           // OutputLimit applies independently to stdout and stderr
}

Tool defines one executable and its complete process boundary

type WorkflowReference

type WorkflowReference struct {
	Kind            WorkflowReferenceKind // Kind identifies action or image semantics
	Value           string                // Value is the exact source reference
	Version         string                // Version is the adjacent stable action tag
	ExcludedVersion string                // ExcludedVersion is one incompatible latest action tag
	ExclusionReason string                // ExclusionReason explains that exact incompatibility
	Path            string                // Path is the repository-relative owning file when read from disk
	Line            int                   // Line is the execution-site source line
}

WorkflowReference retains one governed execution reference

func InspectWorkflowReferences

func InspectWorkflowReferences(source []byte) ([]WorkflowReference, error)

InspectWorkflowReferences parses one bounded workflow without filesystem resolution

type WorkflowReferenceKind

type WorkflowReferenceKind uint8

WorkflowReferenceKind distinguishes action and container execution material

const (
	WorkflowAction WorkflowReferenceKind = iota
	WorkflowImage
)