instrument

Documentation

Overview

Package instrument rewrites copied Go files for AST coverage probes. It never writes an analyzer.File's original source path.

Index

• func InstrumentFile(copyPath string, analysis analyzer.File, helperName string) error
• func SelectHelperName(ctx context.Context, activeFiles []string) (string, error)
• func WriteBridge(options BridgeOptions) (string, error)
• type BridgeOptions
• type FileMapping
• type GeneratedRegion
• type PackageOptions
• type PackageResult
  • func InstrumentPackage(options PackageOptions) (PackageResult, error)
• type SourceMap

Functions

func InstrumentFile

func InstrumentFile(copyPath string, analysis analyzer.File, helperName string) error

InstrumentFile transforms one copied file using analysis from its unchanged original. It rejects the original itself, symlinks/hardlinks to it, and stale copies whose bytes differ from the analyzed source.

func SelectHelperName

func SelectHelperName(ctx context.Context, activeFiles []string) (string, error)

SelectHelperName scans every supplied source/test file and returns a package- wide identifier absent from all of them.

func WriteBridge

func WriteBridge(options BridgeOptions) (string, error)

WriteBridge creates one generated bridge file without overwriting an existing file. User source imports remain untouched.

Types

type BridgeOptions

type BridgeOptions struct {
	Directory         string
	PackageName       string
	PackagePath       string
	RuntimeImportPath string
	HelperName        string
	TestOnly          bool
}

BridgeOptions describes a generated same-package import bridge.

type FileMapping

type FileMapping struct {
	CopyPath string
	Analysis analyzer.File
}

FileMapping maps analysis of an original file to its unchanged copied path.

type GeneratedRegion

type GeneratedRegion struct {
	Kind           string
	Anchor         cover.SourceLocation
	StatementCount uint32
}

GeneratedRegion identifies instrumentation-only statements which Go's cover tool may merge into a user block even when //line uses a virtual file. Consumers should derive statement coverage from the original statement inventory and use this manifest to subtract/ignore synthetic statements.

type PackageOptions

type PackageOptions struct {
	Context                 context.Context
	Directory               string
	PackageName             string
	PackagePath             string
	RuntimeImportPath       string
	CompilerClauseSelection bool
	TestOnly                bool
	ActiveFiles             []string
	Files                   []FileMapping
}

PackageOptions describes one copied package to instrument. ActiveFiles must include every build-active source and test file whose identifiers may collide with the generated package-wide helper.

type PackageResult

type PackageResult struct {
	HelperName     string
	BridgePath     string
	GeneratedFiles []string
	SourceMaps     []SourceMap
}

PackageResult identifies the generated bridge and helper used by rewritten files.

func InstrumentPackage

func InstrumentPackage(options PackageOptions) (PackageResult, error)

InstrumentPackage selects one collision-free helper name, validates and transforms every requested copied file, then creates the generated bridge.

type SourceMap

type SourceMap struct {
	InstrumentedFile string
	OriginalFile     string
	GeneratedFile    string
	CompilerFile     string
	GeneratedRegions []GeneratedRegion
	LineMappings     []analyzer.LineMapping
}

SourceMap identifies the original logical filename used by printer.SourcePos, the virtual filename requested for synthetic statements, and the manifest needed when Go cover retains the physical filename despite //line directives.