Documentation

Overview

    Package lint provides lint functions for Google APIs that register rules and user configurations, apply those rules to a lint request, and produce lint results.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type Config

    type Config struct {
    	IncludedPaths []string `json:"included_paths" yaml:"included_paths"`
    	ExcludedPaths []string `json:"excluded_paths" yaml:"excluded_paths"`
    	EnabledRules  []string `json:"enabled_rules" yaml:"enabled_rules"`
    	DisabledRules []string `json:"disabled_rules" yaml:"disabled_rules"`
    }

      Config stores rule configurations for certain files that the file path must match any of the included paths but none of the excluded ones.

      type Configs

      type Configs []Config

        Configs determine if a rule is enabled or not on a file path.

        func ReadConfigsFromFile

        func ReadConfigsFromFile(path string) (Configs, error)

          ReadConfigsFromFile reads Configs from a file. It supports JSON(.json) and YAML(.yaml or .yml) files.

          func ReadConfigsJSON

          func ReadConfigsJSON(f io.Reader) (Configs, error)

            ReadConfigsJSON reads Configs from a JSON file.

            func ReadConfigsYAML

            func ReadConfigsYAML(f io.Reader) (Configs, error)

              ReadConfigsYAML reads Configs from a JSON file.

              func (Configs) IsRuleEnabled

              func (configs Configs) IsRuleEnabled(rule string, path string) bool

                IsRuleEnabled returns true if a rule is enabled by the configs.

                type DescriptorRule

                type DescriptorRule struct {
                	Name RuleName
                
                	// LintDescriptor accepts a generic descriptor and lints it.
                	//
                	// Note: Unless the descriptor is typecast to a more specific type,
                	// only a subset of methods are available to it.
                	LintDescriptor func(desc.Descriptor) []Problem
                
                	// OnlyIf accepts a Descriptor and determines whether this rule
                	// is applicable.
                	OnlyIf func(desc.Descriptor) bool
                	// contains filtered or unexported fields
                }

                  DescriptorRule defines a lint rule that is run on every descriptor in the file (but not the file itself).

                  func (*DescriptorRule) GetName

                  func (r *DescriptorRule) GetName() RuleName

                    GetName returns the name of the rule.

                    func (*DescriptorRule) Lint

                    func (r *DescriptorRule) Lint(fd *desc.FileDescriptor) []Problem

                      Lint visits every descriptor in the file and runs `LintDescriptor`.

                      It visits every service, method, message, field, enum, and enum value. This order is not guaranteed. It does NOT visit the file itself.

                      type EnumRule

                      type EnumRule struct {
                      	Name RuleName
                      
                      	// LintEnum accepts a EnumDescriptor and lints it.
                      	LintEnum func(*desc.EnumDescriptor) []Problem
                      
                      	// OnlyIf accepts an EnumDescriptor and determines whether this rule
                      	// is applicable.
                      	OnlyIf func(*desc.EnumDescriptor) bool
                      	// contains filtered or unexported fields
                      }

                        EnumRule defines a lint rule that is run on each enum.

                        func (*EnumRule) GetName

                        func (r *EnumRule) GetName() RuleName

                          GetName returns the name of the rule.

                          func (*EnumRule) Lint

                          func (r *EnumRule) Lint(fd *desc.FileDescriptor) []Problem

                            Lint visits every enum in the file and runs `LintEnum`.

                            If an `OnlyIf` function is provided on the rule, it is run against each enum, and if it returns false, the `LintEnum` function is not called.

                            type EnumValueRule

                            type EnumValueRule struct {
                            	Name RuleName
                            
                            	// LintEnumValue accepts a EnumValueDescriptor and lints it.
                            	LintEnumValue func(*desc.EnumValueDescriptor) []Problem
                            
                            	// OnlyIf accepts an EnumValueDescriptor and determines whether this rule
                            	// is applicable.
                            	OnlyIf func(*desc.EnumValueDescriptor) bool
                            	// contains filtered or unexported fields
                            }

                              EnumValueRule defines a lint rule that is run on each enum value.

                              func (*EnumValueRule) GetName

                              func (r *EnumValueRule) GetName() RuleName

                                GetName returns the name of the rule.

                                func (*EnumValueRule) Lint

                                func (r *EnumValueRule) Lint(fd *desc.FileDescriptor) []Problem

                                  Lint visits every enum value in the file and runs `LintEnum`.

                                  If an `OnlyIf` function is provided on the rule, it is run against each enum value, and if it returns false, the `LintEnum` function is not called.

                                  type FieldRule

                                  type FieldRule struct {
                                  	Name RuleName
                                  
                                  	// LintField accepts a FieldDescriptor and lints it, returning a slice of
                                  	// Problems it finds.
                                  	LintField func(*desc.FieldDescriptor) []Problem
                                  
                                  	// OnlyIf accepts a FieldDescriptor and determines whether this rule
                                  	// is applicable.
                                  	OnlyIf func(*desc.FieldDescriptor) bool
                                  	// contains filtered or unexported fields
                                  }

                                    FieldRule defines a lint rule that is run on each field within a file.

                                    func (*FieldRule) GetName

                                    func (r *FieldRule) GetName() RuleName

                                      GetName returns the name of the rule.

                                      func (*FieldRule) Lint

                                      func (r *FieldRule) Lint(fd *desc.FileDescriptor) []Problem

                                        Lint visits every field in the file and runs `LintField`.

                                        If an `OnlyIf` function is provided on the rule, it is run against each field, and if it returns false, the `LintField` function is not called.

                                        type FileRule

                                        type FileRule struct {
                                        	Name RuleName
                                        
                                        	// LintFile accepts a FileDescriptor and lints it, returning a slice of
                                        	// Problems it finds.
                                        	LintFile func(*desc.FileDescriptor) []Problem
                                        
                                        	// OnlyIf accepts a FileDescriptor and determines whether this rule
                                        	// is applicable.
                                        	OnlyIf func(*desc.FileDescriptor) bool
                                        	// contains filtered or unexported fields
                                        }

                                          FileRule defines a lint rule that checks a file as a whole.

                                          func (*FileRule) GetName

                                          func (r *FileRule) GetName() RuleName

                                            GetName returns the name of the rule.

                                            func (*FileRule) Lint

                                            func (r *FileRule) Lint(fd *desc.FileDescriptor) []Problem

                                              Lint forwards the FileDescriptor to the LintFile method defined on the FileRule.

                                              type Linter

                                              type Linter struct {
                                              	// contains filtered or unexported fields
                                              }

                                                Linter checks API files and returns a list of detected problems.

                                                func New

                                                func New(rules RuleRegistry, configs Configs) *Linter

                                                  New creates and returns a linter with the given rules and configs.

                                                  func (*Linter) LintProtos

                                                  func (l *Linter) LintProtos(files ...*desc.FileDescriptor) ([]Response, error)

                                                    LintProtos checks protobuf files and returns a list of problems or an error.

                                                    type MessageRule

                                                    type MessageRule struct {
                                                    	Name RuleName
                                                    
                                                    	// LintMessage accepts a MessageDescriptor and lints it, returning a slice
                                                    	// of Problems it finds.
                                                    	LintMessage func(*desc.MessageDescriptor) []Problem
                                                    
                                                    	// OnlyIf accepts a MessageDescriptor and determines whether this rule
                                                    	// is applicable.
                                                    	OnlyIf func(*desc.MessageDescriptor) bool
                                                    	// contains filtered or unexported fields
                                                    }

                                                      MessageRule defines a lint rule that is run on each message in the file.

                                                      Both top-level messages and nested messages are visited.

                                                      func (*MessageRule) GetName

                                                      func (r *MessageRule) GetName() RuleName

                                                        GetName returns the name of the rule.

                                                        func (*MessageRule) Lint

                                                        func (r *MessageRule) Lint(fd *desc.FileDescriptor) []Problem

                                                          Lint visits every message in the file, and runs `LintMessage`.

                                                          If an `OnlyIf` function is provided on the rule, it is run against each message, and if it returns false, the `LintMessage` function is not called.

                                                          type MethodRule

                                                          type MethodRule struct {
                                                          	Name RuleName
                                                          
                                                          	// LintMethod accepts a MethodDescriptor and lints it.
                                                          	LintMethod func(*desc.MethodDescriptor) []Problem
                                                          
                                                          	// OnlyIf accepts a MethodDescriptor and determines whether this rule
                                                          	// is applicable.
                                                          	OnlyIf func(*desc.MethodDescriptor) bool
                                                          	// contains filtered or unexported fields
                                                          }

                                                            MethodRule defines a lint rule that is run on each method.

                                                            func (*MethodRule) GetName

                                                            func (r *MethodRule) GetName() RuleName

                                                              GetName returns the name of the rule.

                                                              func (*MethodRule) Lint

                                                              func (r *MethodRule) Lint(fd *desc.FileDescriptor) []Problem

                                                                Lint visits every method in the file and runs `LintMethod`.

                                                                If an `OnlyIf` function is provided on the rule, it is run against each method, and if it returns false, the `LintMethod` function is not called.

                                                                type Problem

                                                                type Problem struct {
                                                                	// Message provides a short description of the problem.
                                                                	// This should be no more than a single sentence.
                                                                	Message string
                                                                
                                                                	// Suggestion provides a suggested fix, if applicable.
                                                                	//
                                                                	// This integrates with certain IDEs to provide "push-button" fixes,
                                                                	// so these need to be machine-readable, not just human-readable.
                                                                	// Additionally, when setting `Suggestion`, one should almost always set
                                                                	// `Location` also, to ensure that the text being replaced is sufficiently
                                                                	// precise.
                                                                	Suggestion string
                                                                
                                                                	// 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 desc.Descriptor
                                                                
                                                                	// Location provides the location of the problem.
                                                                	//
                                                                	// If unset, this defaults to the value of `Descriptor.GetSourceInfo()`.
                                                                	// This should almost always be set if `Suggestion` is set. The best way to
                                                                	// do this is by using the helper methods in `location.go`.
                                                                	Location *dpb.SourceCodeInfo_Location
                                                                
                                                                	// RuleID provides the ID of the rule that this problem belongs to.
                                                                	// DO NOT SET: The linter sets this automatically.
                                                                	RuleID RuleName // FIXME: Make this private (cmd/summary_cli.go is the challenge).
                                                                	// contains filtered or unexported fields
                                                                }

                                                                  Problem contains information about a result produced by an API Linter.

                                                                  All rules return []Problem. Most lint rules return 0 or 1 problems, but occasionally there are rules that may return more than one.

                                                                  func (Problem) MarshalJSON

                                                                  func (p Problem) MarshalJSON() ([]byte, error)

                                                                    MarshalJSON defines how to represent a Problem in JSON.

                                                                    func (Problem) MarshalYAML

                                                                    func (p Problem) MarshalYAML() (interface{}, error)

                                                                      MarshalYAML defines how to represent a Problem in YAML.

                                                                      type ProtoRule

                                                                      type ProtoRule interface {
                                                                      	// GetName returns the name of the rule.
                                                                      	GetName() RuleName
                                                                      
                                                                      	// Lint accepts a FileDescriptor and lints it,
                                                                      	// returning a slice of Problem objects it finds.
                                                                      	Lint(*desc.FileDescriptor) []Problem
                                                                      }

                                                                        ProtoRule defines a lint rule that checks Google Protobuf APIs.

                                                                        Anything that satisfies this interface can be used as a rule, but most rule authors will want to use the implementations provided.

                                                                        Rules must only report errors in the file under which they are being run (not imported files).

                                                                        type Response

                                                                        type Response struct {
                                                                        	FilePath string    `json:"file_path" yaml:"file_path"`
                                                                        	Problems []Problem `json:"problems" yaml:"problems"`
                                                                        }

                                                                          Response describes the result returned by a rule.

                                                                          type RuleName

                                                                          type RuleName string

                                                                            RuleName is an identifier for a rule. Allowed characters include a-z, 0-9, -.

                                                                            The namespace separator :: is allowed between RuleName segments (for example, my-namespace::my-rule).

                                                                            func NewRuleName

                                                                            func NewRuleName(aip int, name string) RuleName

                                                                              NewRuleName creates a RuleName from an AIP number and a unique name within that AIP.

                                                                              func (RuleName) HasPrefix

                                                                              func (r RuleName) HasPrefix(prefix ...string) bool

                                                                                HasPrefix returns true if r contains prefix as a namespace. prefix parameters can be "::" delimited or specified as independent parameters. For example:

                                                                                r := NewRuleName("foo", "bar", "baz") // string(r) == "foo::bar::baz"

                                                                                r.HasPrefix("foo::bar") == true r.HasPrefix("foo", "bar") == true r.HasPrefix("foo", "bar", "baz") == true // matches the entire string r.HasPrefix("foo", "ba") == false // prefix must end on a delimiter

                                                                                func (RuleName) IsValid

                                                                                func (r RuleName) IsValid() bool

                                                                                  IsValid checks if a RuleName is syntactically valid.

                                                                                  type RuleRegistry

                                                                                  type RuleRegistry map[RuleName]ProtoRule

                                                                                    RuleRegistry is a registry for registering and looking up rules.

                                                                                    func NewRuleRegistry

                                                                                    func NewRuleRegistry() RuleRegistry

                                                                                      NewRuleRegistry creates a new rule registry.

                                                                                      func (RuleRegistry) Register

                                                                                      func (r RuleRegistry) Register(aip int, rules ...ProtoRule) error

                                                                                        Register registers the list of rules of the same AIP. Return an error if any of the rules is found duplicate in the registry.

                                                                                        type ServiceRule

                                                                                        type ServiceRule struct {
                                                                                        	Name RuleName
                                                                                        
                                                                                        	// LintService accepts a ServiceDescriptor and lints it.
                                                                                        	LintService func(*desc.ServiceDescriptor) []Problem
                                                                                        
                                                                                        	// OnlyIf accepts a ServiceDescriptor and determines whether this rule
                                                                                        	// is applicable.
                                                                                        	OnlyIf func(*desc.ServiceDescriptor) bool
                                                                                        	// contains filtered or unexported fields
                                                                                        }

                                                                                          ServiceRule defines a lint rule that is run on each service.

                                                                                          func (*ServiceRule) GetName

                                                                                          func (r *ServiceRule) GetName() RuleName

                                                                                            GetName returns the name of the rule.

                                                                                            func (*ServiceRule) Lint

                                                                                            func (r *ServiceRule) Lint(fd *desc.FileDescriptor) []Problem

                                                                                              Lint visits every service in the file and runs `LintService`.

                                                                                              If an `OnlyIf` function is provided on the rule, it is run against each service, and if it returns false, the `LintService` function is not called.