cmd/goapi: new tool for tracking exported API over time

The idea is that we add files to the api/ directory which
are sets of promises for the future.  Each line in a file
is a stand-alone feature description.

When we do a release, we make sure we haven't broken or changed
any lines from the past (only added them).

We never change old files, only adding new ones. (go-1.1.txt,
etc)

R=dsymonds, adg, r, remyoudompheng, rsc
CC=golang-dev
https://golang.org/cl/5570051

src/cmd/goapi/goapi_test.go

+// Copyright 2011 The Go Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+import (
+	"flag"
+	"fmt"
+	"io/ioutil"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"testing"
+)
+
+var (
+	updateGolden = flag.Bool("updategolden", false, "update golden files")
+)
+
+func TestGolden(t *testing.T) {
+	td, err := os.Open("testdata")
+	if err != nil {
+		t.Fatal(err)
+	}
+	fis, err := td.Readdir(0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, fi := range fis {
+		if !fi.IsDir() {
+			continue
+		}
+		w := NewWalker()
+		goldenFile := filepath.Join("testdata", fi.Name(), "golden.txt")
+
+		w.WalkPackage(fi.Name(), filepath.Join("testdata", fi.Name()))
+
+		if *updateGolden {
+			os.Remove(goldenFile)
+			f, err := os.Create(goldenFile)
+			if err != nil {
+				t.Fatal(err)
+			}
+			for _, feat := range w.Features() {
+				fmt.Fprintf(f, "%s\n", feat)
+			}
+			f.Close()
+		}
+
+		bs, err := ioutil.ReadFile(goldenFile)
+		if err != nil {
+			t.Fatalf("opening golden.txt for package %q: %v", fi.Name(), err)
+		}
+		wanted := strings.Split(string(bs), "\n")
+		sort.Strings(wanted)
+		for _, feature := range wanted {
+			if feature == "" {
+				continue
+			}
+			_, ok := w.features[feature]
+			if !ok {
+				t.Errorf("package %s: missing feature %q", fi.Name(), feature)
+			}
+			delete(w.features, feature)
+		}
+
+		for _, feature := range w.Features() {
+			t.Errorf("package %s: extra feature not in golden file: %q", fi.Name(), feature)
+		}
+	}
+}

src/cmd/goapi/testdata/p1/golden.txt

+pkg p1, const A ideal-int
+pkg p1, const A64 int64
+pkg p1, const B ideal-int
+pkg p1, const ConversionConst MyInt
+pkg p1, const FloatConst ideal-float
+pkg p1, const StrConst ideal-string
+pkg p1, func Bar(int8, int16, int64)
+pkg p1, func Bar1(int8, int16, int64) uint64
+pkg p1, func Bar2(int8, int16, int64) (uint8, uint64)
+pkg p1, func TakesFunc(func(int) int)
+pkg p1, method (*B) JustOnB()
+pkg p1, method (*B) OnBothTandBPtr()
+pkg p1, method (*Embedded) OnEmbedded()
+pkg p1, method (*S2) SMethod(int8, int16, int64)
+pkg p1, method (*T) JustOnT()
+pkg p1, method (*T) OnBothTandBPtr()
+pkg p1, method (B) OnBothTandBVal()
+pkg p1, method (S) StructValueMethod()
+pkg p1, method (S) StructValueMethodNamedRecv()
+pkg p1, method (S2) StructValueMethod()
+pkg p1, method (S2) StructValueMethodNamedRecv()
+pkg p1, method (T) OnBothTandBVal()
+pkg p1, method (TPtrExported) OnEmbedded()
+pkg p1, method (TPtrUnexported) OnBothTandBPtr()
+pkg p1, method (TPtrUnexported) OnBothTandBVal()
+pkg p1, type B struct
+pkg p1, type Codec struct
+pkg p1, type Codec struct, Func func(int, int) int
+pkg p1, type EmbedSelector struct
+pkg p1, type EmbedSelector struct, embedded time.Time
+pkg p1, type EmbedURLPtr struct
+pkg p1, type EmbedURLPtr struct, embedded *url.URL
+pkg p1, type Embedded struct
+pkg p1, type I interface { Get, GetNamed, Set }
+pkg p1, type I interface, Get(string) int64
+pkg p1, type I interface, GetNamed(string) int64
+pkg p1, type I interface, Set(string, int64)
+pkg p1, type MyInt int
+pkg p1, type S struct
+pkg p1, type S struct, Public *int
+pkg p1, type S struct, PublicTime time.Time
+pkg p1, type S2 struct
+pkg p1, type S2 struct, Extra bool
+pkg p1, type S2 struct, embedded S
+pkg p1, type SI struct
+pkg p1, type SI struct, I int
+pkg p1, type T struct
+pkg p1, type TPtrExported struct
+pkg p1, type TPtrExported struct, embedded *Embedded
+pkg p1, type TPtrUnexported struct
+pkg p1, var ChecksumError error
+pkg p1, var SIPtr *SI
+pkg p1, var SIPtr2 *SI
+pkg p1, var SIVal SI
+pkg p1, var X I
+pkg p1, var X int64
+pkg p1, var Y int

src/cmd/goapi/testdata/p1/p1.go

+package foo
+
+import (
+	"time"
+	"url"
+)
+
+const (
+	A         = 1
+	a         = 11
+	A64 int64 = 1
+)
+
+const (
+	ConversionConst = MyInt(5)
+)
+
+var ChecksumError = errors.New("gzip checksum error")
+
+const B = 2
+const StrConst = "foo"
+const FloatConst = 1.5
+
+type myInt int
+
+type MyInt int
+
+type S struct {
+	Public     *int
+	private    *int
+	PublicTime time.Time
+}
+
+type EmbedURLPtr struct {
+	*url.URL
+}
+
+type S2 struct {
+	S
+	Extra bool
+}
+
+var X int64
+
+var (
+	Y int
+	X I // todo: resolve this to foo.I? probably doesn't matter.
+)
+
+type I interface {
+	Set(name string, balance int64)
+	Get(string) int64
+	GetNamed(string) (balance int64)
+	private()
+}
+
+func (myInt) privateTypeMethod()           {}
+func (myInt) CapitalMethodUnexportedType() {}
+
+func (s *S2) SMethod(x int8, y int16, z int64) {}
+
+type s struct{}
+
+func (s) method()
+func (s) Method()
+
+func (S) StructValueMethod()
+func (ignored S) StructValueMethodNamedRecv()
+
+func (s *S2) unexported(x int8, y int16, z int64) {}
+
+func Bar(x int8, y int16, z int64)                  {}
+func Bar1(x int8, y int16, z int64) uint64          {}
+func Bar2(x int8, y int16, z int64) (uint8, uint64) {}
+
+func unexported(x int8, y int16, z int64) {}
+
+func TakesFunc(f func(dontWantName int) int)
+
+type Codec struct {
+	Func func(x int, y int) (z int)
+}
+
+type SI struct {
+	I int
+}
+
+var SIVal = SI{}
+var SIPtr = &SI{}
+var SIPtr2 *SI
+
+type T struct {
+	common
+}
+
+type B struct {
+	common
+}
+
+type common struct {
+	i int
+}
+
+type TPtrUnexported struct {
+	*common
+}
+
+type TPtrExported struct {
+	*Embedded
+}
+
+type Embedded struct{}
+
+func (*Embedded) OnEmbedded() {}
+
+func (*T) JustOnT()             {}
+func (*B) JustOnB()             {}
+func (*common) OnBothTandBPtr() {}
+func (common) OnBothTandBVal()  {}
+
+type EmbedSelector struct {
+	time.Time
+}