deadcode

Documentation

Overview

Package deadcode finds the source functions no program in a module can reach, and removes the ones that are dead by construction.

Reachability is golang.org/x/tools' deadcode analysis: every main package and every test executable is a root, rapid type analysis computes what they reach, and a function declared in source but reached by none is dead. Functions in generated files and interface marker methods are never reported.

Dead is not the same as removable. An exported function of a library package is that package's contract; a caller outside the module, or one not yet written, may need it, so it is reported and kept. Everything no other package could ever call is removable: an unexported function, any function of a main package, and any function in a _test.go file.

Index

• Variables
• func Remove(functions []Function) (map[string][]byte, error)
• type Function
  • func Find(dir string, patterns ...string) ([]Function, error)
  • func Fix(dir string, patterns ...string) ([]Function, error)
  • func (function Function) Protected() bool
  • func (function Function) Removable() bool
  • func (function Function) String() string

Variables

var (
	// ErrNoMains reports patterns that hold no main package and no test, so
	// nothing is a root and every function would read as dead.
	ErrNoMains = errors.New("deadcode: the patterns hold no main package or test to reach anything from")
	// ErrLoad reports packages that do not load or type-check.
	ErrLoad = errors.New("deadcode: packages do not type-check")
	// ErrNotFound reports a function Remove cannot find at its position.
	ErrNotFound = errors.New("deadcode: no function declaration at the recorded position")
	// ErrProtected reports a removal of this package's own source.
	ErrProtected = errors.New("deadcode: the remover never edits its own package")
)

Functions

func Remove

func Remove(functions []Function) (map[string][]byte, error)

Remove deletes the declarations of functions, with their doc comments, and returns each rewritten file's new content keyed by path, formatted and with the imports nothing uses any more removed. It writes nothing.

Types

type Function

type Function struct {
	// Position is where its name is declared.
	Position token.Position
	// Name is Receiver.Method or Function.
	Name string
	// Package is its import path.
	Package string
	// Exported reports an exported name on an exported (or no) receiver.
	Exported bool
	// InMain reports a function of a main package.
	InMain bool
	// InTest reports a function declared in a _test.go file.
	InTest bool
	// Satisfies reports a method its type needs to satisfy an interface
	// it is converted to: nothing calls it, yet the build does.
	Satisfies bool
}

Function is one source function nothing reaches.

func Find

func Find(dir string, patterns ...string) ([]Function, error)

Find loads patterns, relative to dir, with their tests and returns every source function of the module no main package or test reaches, ordered by file and line.

func Fix

func Fix(dir string, patterns ...string) ([]Function, error)

Fix removes every removable dead function under patterns until a pass removes nothing, and returns what it removed. Removals are tried a directory at a time and kept only while that directory's package and its tests still type-check; a directory that breaks is retried one function at a time, and a function whose removal breaks the build is kept, which is how a method an interface needs survives.

func (Function) Protected

func (function Function) Protected() bool

Protected reports a function of this package: the remover never edits its own source, whatever the analysis says about it.

func (Function) Removable

func (function Function) Removable() bool

Removable reports a function no other package could ever call, so its being unreachable makes it dead for every caller there will ever be, and that no interface its type is converted to needs.

func (Function) String

func (function Function) String() string

String is the function as deadcode prints it, path:line:col: name.