Core skeleton

.gitignore

@@ -0,0 +1,2 @@
+.idea
+.vscode

go.mod

@@ -0,0 +1,10 @@
+module github.com/jgeewax/api-linter
+
+go 1.12
+
+require (
+	github.com/golang/protobuf/v2 v2.0.0-20190115031900-66c365cf7239
+	github.com/google/go-cmp v0.2.1-0.20181101181452-745b8ec83783
+	github.com/iancoleman/strcase v0.0.0-20180726023541-3605ed457bf7
+	github.com/stretchr/testify v1.3.0
+)

go.sum

@@ -0,0 +1,24 @@
+github.com/davecgh/go-spew v1.1.0 h1:ZDRjVQ15GmhC3fiQ8ni8+OwkZQO4DARzQgrnXU1Liz8=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/golang/protobuf v1.2.1-0.20181127190454-8d0c54c12466/go.mod h1:Qd/q+1AKNOZr9uGQzbzCmRO6sUih6GTPZv6a1/R87v0=
+github.com/golang/protobuf v1.2.1-0.20181205191652-7e65e513332f h1:jEoef3K+ZQwZ7UB1iGu6KhX8hS9cYw1aXR7djS3Vn10=
+github.com/golang/protobuf v1.2.1-0.20181205191652-7e65e513332f/go.mod h1:asK8yRb/+zxJTE0SbTESCku/4OjiDfbPwk4rEyIatUA=
+github.com/golang/protobuf/v2 v2.0.0-20181127193627-d7e97bc71bcb/go.mod h1:MgUD+N3FwzDmj2CdMsT5ap7K7jx+c9cQDQ7fVhmH+Xw=
+github.com/golang/protobuf/v2 v2.0.0-20190115031900-66c365cf7239 h1:gRJbl/8g6n9YmDWRAI93uRuIVnw/ESX2o/SMfLO3QOY=
+github.com/golang/protobuf/v2 v2.0.0-20190115031900-66c365cf7239/go.mod h1:sjQt90Yu/7/I4QgfZq+CzFOly7327WbVZ1EDQjIlnMI=
+github.com/google/go-cmp v0.2.1-0.20181101181452-745b8ec83783 h1:wVZ6laEGf86tNDTpR5mxFyFIclJJiXCxuJhcQKnsOHk=
+github.com/google/go-cmp v0.2.1-0.20181101181452-745b8ec83783/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
+github.com/iancoleman/strcase v0.0.0-20180726023541-3605ed457bf7 h1:ux/56T2xqZO/3cP1I2F86qpeoYPCOzk+KF/UH/Ar+lk=
+github.com/iancoleman/strcase v0.0.0-20180726023541-3605ed457bf7/go.mod h1:SK73tn/9oHe+/Y0h39VT4UCxmurVJkR5NA7kMEAOgSE=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0 h1:4G4v2dO3VZwixGIRoQ5Lfboy6nUhCyYzaqnIAPPhYs4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0 h1:TivCn/peBQ7UY8ooIcPgZFpTNSz0Q2U6UrFlUfqbe0Q=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20180926154720-4dfa2610cdf3/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/tools v0.0.0-20180904205237-0aa4b8830f48/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20180928181343-b3c0be4c978b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+google.golang.org/genproto v0.0.0-20180831171423-11092d34479b/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=

lint/location.go

@@ -0,0 +1,24 @@
+package lint
+
+// Location describes a location in a source code file.
+type Location struct {
+	Start, End Position
+}
+
+// IsValid checks if the location struct is constructed properly and
+// returns true if it's valid.
+func (l Location) IsValid() bool {
+	return l.Start.IsValid() && l.End.IsValid()
+}
+
+// Position describes a zero-based position in a source code file.
+// Typically you will want to add 1 to each before displaying to a user.
+type Position struct {
+	Line, Column int
+}
+
+// IsValid checks if the position struct is constructed properly and
+// returns true if it's valid.
+func (p Position) IsValid() bool {
+	return p.Line >= 0 && p.Column >= 0
+}

lint/problem.go

@@ -0,0 +1,22 @@
+package lint
+
+import (
+	"github.com/golang/protobuf/v2/reflect/protoreflect"
+)
+
+// Problem contains information about a result produced by an API Linter.
+type Problem struct {
+	// Message provides a short description of the problem.
+	Message string
+	// Suggestion provides a suggested fix, if applicable.
+	Suggestion string
+	// Location provides the location of the problem. If both
+	// `Location` and `Descriptor` are specified, the location
+	// is then used from `Location` instead of `Descriptor`.
+	Location Location
+	// Descriptor provides the descriptor related
+	// to the problem. If present and `Location` is not
+	// specified, then the starting location of the descriptor
+	// is used as the location of the problem.
+	Descriptor protoreflect.Descriptor
+}

lint/request.go

@@ -0,0 +1,37 @@
+package lint
+
+import (
+	"github.com/golang/protobuf/v2/reflect/protodesc"
+	"github.com/golang/protobuf/v2/reflect/protoreflect"
+	descriptorpb "github.com/golang/protobuf/v2/types/descriptor"
+)
+
+// Request defines input data for a rule to perform linting.
+type Request struct {
+	fileDesc   protoreflect.FileDescriptor
+	descSource DescriptorSource
+}
+
+// ProtoFile returns a FileDescriptor of the .proto file that will be linted.
+func (r Request) ProtoFile() protoreflect.FileDescriptor {
+	return r.fileDesc
+}
+
+// DescriptorSource returns a DescriptorSource that contains additional source
+// information for the .proto file that will be linted.
+func (r Request) DescriptorSource() DescriptorSource {
+	return r.descSource
+}
+
+// NewProtoFileRequest creates a linting Request for a .proto file.
+func NewProtoFileRequest(fd *descriptorpb.FileDescriptorProto) (Request, error) {
+	f, err := protodesc.NewFile(fd, nil)
+	if err != nil {
+		return Request{}, err
+	}
+	s, err := newDescriptorSource(fd)
+	return Request{
+		fileDesc:   f,
+		descSource: s,
+	}, err
+}

lint/response.go

@@ -0,0 +1,11 @@
+package lint
+
+// Response describes the result returned by a rule.
+type Response struct {
+	Problems []Problem
+}
+
+// merge merges another response.
+func (resp *Response) merge(other Response) {
+	resp.Problems = append(resp.Problems, other.Problems...)
+}

lint/rule.go

@@ -0,0 +1,50 @@
+package lint
+
+// Rule defines a lint rule that checks Google Protobuf APIs.
+type Rule interface {
+	// ID returns the unique `RuleID` for this rule.
+	ID() RuleID
+	// Description returns a short summary about this rule.
+	Description() string
+	// URL returns a link at which the full documentation
+	// about this rule can be accessed.
+	URL() string
+	// FileTypes returns the types of files that this rule is targeting to.
+	// E.g., `ProtoFile` for protobuf files.
+	FileTypes() []FileType
+	// Category returns the category of findings produced
+	// by this rule, e.g. Problem, Suggestion, etc.
+	Category() Category
+	// Lint performs the linting process.
+	Lint(Request) (Response, error)
+}
+
+// RuleID describes a `Rule` ID.
+type RuleID struct {
+	// Set is where a rule belongs to and usually is the scope
+	// of the contained rules should be applied to. For example,
+	// the `core` set contains all rules that should be applied to
+	// all Google APIs, while the set `google.corpeng` contains rules
+	// that should be applied only to Google Corp Eng APIs.
+	Set string
+	// Name is the unique name in the set.
+	Name string
+}
+
+// FileType defines a file type that a rule is targeting to.
+type FileType string
+
+const (
+	// ProtoFile indicates that the targeted file is a protobuf-definition file.
+	ProtoFile FileType = "proto-file"
+)
+
+// Category defines the category of the findings produced by a rule.
+type Category string
+
+const (
+	// CategoryError indicates that in the API, something will cause errors.
+	CategoryError Category = "API-Linter-Error"
+	// CategorySuggestion indicates that in the API, something can be do better.
+	CategorySuggestion Category = "API-Linter-Suggestion"
+)

lint/rule_config.go

@@ -0,0 +1,12 @@
+package lint
+
+// RulesConfig describes which rule sets to use.
+type RulesConfig struct {
+	RuleSets []RuleSetConfig
+}
+
+// RuleSetConfig describes which rules to be excluded in a set.
+type RuleSetConfig struct {
+	Set           string
+	ExcludedRules []string
+}

lint/rules.go

@@ -0,0 +1,80 @@
+package lint
+
+import (
+	"errors"
+)
+
+var (
+	// ErrDuplicateID is the returned error when a duplicated rule ID is
+	// found in a rule registry.
+	ErrDuplicateID = errors.New("rule registry: found duplicate id")
+	// ErrNotFound is the returned error when a rule is not found in a
+	// rule registry
+	ErrNotFound = errors.New("rule registry: rule is not found")
+)
+
+// Rules is a registry for registering and looking up rules.
+type Rules struct {
+	ruleMap map[RuleID]Rule
+}
+
+// Register registers the list of rules.
+// It returns `ErrDuplicateID` if any of the rules is found duplicate
+// in the registry.
+func (r *Rules) Register(rules ...Rule) error {
+	for _, rl := range rules {
+		if _, found := r.ruleMap[rl.ID()]; found {
+			return ErrDuplicateID
+		}
+		r.ruleMap[rl.ID()] = rl
+	}
+	return nil
+}
+
+// Merge merges another rule registry.
+// If any rule is found duplicate, returns `ErrDuplicateID`.
+func (r *Rules) Merge(other Rules) error {
+	return r.Register(other.All()...)
+}
+
+// FindByConfig looks up a list of rules by a RulesConfig
+func (r *Rules) FindByConfig(cfg RulesConfig) []Rule {
+	rules := []Rule{}
+	for _, setConfig := range cfg.RuleSets {
+		rules = append(rules, r.findBySet(setConfig)...)
+	}
+	return rules
+}
+
+// All returns all rules.
+func (r Rules) All() []Rule {
+	rules := []Rule{}
+	for _, r1 := range r.ruleMap {
+		rules = append(rules, r1)
+	}
+	return rules
+}
+
+func (r *Rules) findBySet(s RuleSetConfig) []Rule {
+	excludedRules := make(map[string]bool)
+	for _, ruleName := range s.ExcludedRules {
+		excludedRules[ruleName] = true
+	}
+
+	rules := []Rule{}
+	for _, r1 := range r.ruleMap {
+		if r1.ID().Set == s.Set && !excludedRules[r1.ID().Name] {
+			rules = append(rules, r1)
+		}
+	}
+	return rules
+}
+
+// NewRules returns a rule registry initialized with the given set of rules.
+func NewRules(rules ...Rule) (*Rules, error) {
+	r := Rules{
+		ruleMap: make(map[RuleID]Rule),
+	}
+	err := r.Register(rules...)
+	return &r, err
+}