gompatible

README

gompatible

Gompatible is a tool to show Go package's API changes between two (git) revisions. The API changes are categorized into unchanged, added, removed, breaking, and compatible.

Installation

go get -u github.com/motemen/gompatible/cmd/gompat

Usage

gompat [-a] [-d] [-r] <rev1>[..[<rev2>]] [<import path>[/...]]

Extracts type information of target package (or the current directory if not specified) at two revisions rev1, rev2 and shows changes between them.

Flags:

-a    show also unchanged APIs
-d    run diff on multi-line changes
-r    recurse into subdirectories
      (can be specified by "/..." suffix to the import path)

Specifying revisions

• <rev1>..<rev2> ... Shows changes between revisions rev1 and rev2
• <rev1>.. ... Shows changes between revisions rev1 and HEAD (same as <rev1>..HEAD)
• <rev1> .. Shows changes introduced by the commit rev1 (same as <rev1>~1..<rev1>)

Example

% gompat 665374f1c86631cf73f4729095d4cf4313670 golang.org/x/tools/go/types
! func Eval(str string, pkg *Package, scope *Scope) (TypeAndValue, error)
. func Eval(fset *token.FileSet, pkg *Package, pos token.Pos, expr string) (tv TypeAndValue, err error)
- func EvalNode(fset *token.FileSet, node ast.Expr, pkg *Package, scope *Scope) (tv TypeAndValue, err error)
- func New(str string) Type
! func NewScope(parent *Scope, comment string) *Scope
. func NewScope(parent *Scope, pos, end token.Pos, comment string) *Scope
...

Details

API entities

API entities, in the sense of Gompatible recognizes, are package-level and exported

• Functions and methods (func),
• Types (type), and
• Variables (var) and constants (const).

API changes

The obvious API change kinds are:

• Unchanged (=)
  • The API entity kept unchanged
• Added (+)
  • The API entity was newly added
• Removed (-)
  • The API entity was removed

And below are the less-obvious ones:

Breaking (!)

The API signature has been changed and the users must change their usages.

Example:

// before
func F(n, m int) error

// after
func F(n, m int, b bool) error

// before
type T struct {
  Foo string
  Bar bool
}

// after
type T struct {
  Foo float64
  Bar bool
}

Compatible (*)

The API signature has been changed, but the users do not have to change their usages.

Example:

// before
func F(n, m int) error

// after
func F(n, m int, opt ...interface{}) error

// before
func F(b *bytes.Buffer)

// after
func F(r io.Reader)

Author

motemen https://motemen.github.io/

Documentation

Index

• Variables
• func Debugf(pat string, args ...interface{})
• func LoadDir(dir *DirSpec, recurse bool) (map[string]*Package, error)
• func LoadPackages(ctx *build.Context, filepaths map[string][]string) (map[string]*Package, error)
• func ShowChange(c Change) string
• type Change
• type ChangeKind
  • func (ck ChangeKind) String() string
• type DirSpec
  • func NewDirSpec(path, vcs, revision string) (*DirSpec, error)
  • func (dir *DirSpec) ReadDir() ([]os.FileInfo, error)
  • func (dir *DirSpec) String() string
• type Func
• type FuncChange
  • func (fc FuncChange) Kind() ChangeKind
  • func (fc FuncChange) ShowAfter() string
  • func (fc FuncChange) ShowBefore() string
  • func (fc FuncChange) TypesObject() types.Object
• type ObjectCategory
• type Package
  • func NewPackage(fset *token.FileSet, doc *doc.Package, types *types.Package) *Package
• type PackageChanges
  • func DiffPackages(pkg1, pkg2 *Package) PackageChanges
  • func (pc PackageChanges) Funcs() map[string]FuncChange
  • func (pc PackageChanges) Path() string
  • func (pc PackageChanges) Types() map[string]TypeChange
  • func (pc PackageChanges) Values() map[string]ValueChange
• type Type
• type TypeChange
  • func (tc TypeChange) Kind() ChangeKind
  • func (tc TypeChange) ShowAfter() string
  • func (tc TypeChange) ShowBefore() string
  • func (tc TypeChange) TypesObject() types.Object
• type Value
• type ValueChange
  • func (vc ValueChange) Kind() ChangeKind
  • func (vc ValueChange) ShowAfter() string
  • func (vc ValueChange) ShowBefore() string
  • func (vc ValueChange) TypesObject() types.Object

Variables

var Debug bool = false

Functions

func Debugf

func Debugf(pat string, args ...interface{})

func LoadDir

func LoadDir(dir *DirSpec, recurse bool) (map[string]*Package, error)

func LoadPackages

func LoadPackages(ctx *build.Context, filepaths map[string][]string) (map[string]*Package, error)

func ShowChange

func ShowChange(c Change) string

ShowChange returns a string represnetation of an API change.

Types

type Change

type Change interface {
	TypesObject() types.Object
	ShowBefore() string
	ShowAfter() string
	Kind() ChangeKind
}

A Change represents a change of an API between two revisions.

type ChangeKind

type ChangeKind int

ChangeKind represents the kind of a change of an API between two revisions.

const (
	ChangeUnchanged ChangeKind = iota
	ChangeAdded
	ChangeRemoved
	ChangeCompatible
	ChangeBreaking
)

func (ChangeKind) String

func (ck ChangeKind) String() string

type DirSpec

type DirSpec struct {
	VCS      string
	Revision string
	Path     string
	// contains filtered or unexported fields
}

DirSpec represents a virtual directory which may point to a source tree of a specific Revision controlled under a VCS.

func NewDirSpec

func NewDirSpec(path, vcs, revision string) (*DirSpec, error)

NewDirSpec creates a virtual directory which may point to a source tree of a specific revision controlled under a vcs. The path may be one of:

• An absolute path
• An import path
• A relative import path

func (*DirSpec) ReadDir

func (dir *DirSpec) ReadDir() ([]os.FileInfo, error)

func (*DirSpec) String

func (dir *DirSpec) String() string

type Func

type Func struct {
	Package *Package
	Types   *types.Func
	Doc     *doc.Func
}

Func is a syntactically parsed, type-checked and (maybe) documented function.

type FuncChange

type FuncChange struct {
	Before *Func
	After  *Func
}

FuncChange represents a change between functions.

func (FuncChange) Kind

func (fc FuncChange) Kind() ChangeKind

func (FuncChange) ShowAfter

func (fc FuncChange) ShowAfter() string

func (FuncChange) ShowBefore

func (fc FuncChange) ShowBefore() string

func (FuncChange) TypesObject

func (fc FuncChange) TypesObject() types.Object

type ObjectCategory

type ObjectCategory string

ObjectCategory is the category of API.

const (
	ObjectCategoryFunc  ObjectCategory = "func"
	ObjectCategoryType  ObjectCategory = "type"
	ObjectCategoryValue ObjectCategory = "value"
)

type Package

type Package struct {
	// The types aspect of the package
	TypesPkg *types.Package
	// The docs aspect of the package
	DocPkg *doc.Package

	Funcs  map[string]*Func
	Types  map[string]*Type
	Values map[string]*Value

	Fset *token.FileSet
}

Package represents a parsed, type-checked and documented package.

func NewPackage

func NewPackage(fset *token.FileSet, doc *doc.Package, types *types.Package) *Package

NewPackage builds a Package from one from doc and types package.

type PackageChanges

type PackageChanges struct {
	Before  *Package
	After   *Package
	Changes map[ObjectCategory]map[string]Change
}

PackageChanges represent changes between two packages.

func DiffPackages

func DiffPackages(pkg1, pkg2 *Package) PackageChanges

DiffPackages takes two packages to produce the changes between them.

func (PackageChanges) Funcs

func (pc PackageChanges) Funcs() map[string]FuncChange

Funcs returns API changes of functions.

func (PackageChanges) Path

func (pc PackageChanges) Path() string

Path is the import path of the package.

func (PackageChanges) Types

func (pc PackageChanges) Types() map[string]TypeChange

Types returns API changes of types.

func (PackageChanges) Values

func (pc PackageChanges) Values() map[string]ValueChange

Types returns API changes of values eg. consts and vars.

type Type

type Type struct {
	Package *Package
	Types   *types.TypeName
	Doc     *doc.Type
	Funcs   map[string]*Func
	Methods map[string]*Func
}

Type is a syntactically parsed, type-checked and (maybe) documented type declaration.

type TypeChange

type TypeChange struct {
	Before *Type
	After  *Type
}

TypeChange represents a change between two types.

func (TypeChange) Kind

func (tc TypeChange) Kind() ChangeKind

func (TypeChange) ShowAfter

func (tc TypeChange) ShowAfter() string

func (TypeChange) ShowBefore

func (tc TypeChange) ShowBefore() string

func (TypeChange) TypesObject

func (tc TypeChange) TypesObject() types.Object

type Value

type Value struct {
	Name    string
	Package *Package
	Doc     *doc.Value
	Types   types.Object // *types.Var (IsConst == false) or *types.Const (IsConst == true)
	IsConst bool
}

Value is a syntactically parsed, type-checked and (maybe) documented toplevel value (var or const).

type ValueChange

type ValueChange struct {
	Before *Value
	After  *Value
}

func (ValueChange) Kind

func (vc ValueChange) Kind() ChangeKind

func (ValueChange) ShowAfter

func (vc ValueChange) ShowAfter() string

func (ValueChange) ShowBefore

func (vc ValueChange) ShowBefore() string

func (ValueChange) TypesObject

func (vc ValueChange) TypesObject() types.Object