thriftlint

README

An extensible linter for Thrift

This is an extensible linter for Thrift. It includes a set of common lint checks, but allows for both customisation of those checks, and creation of new ones by implementing the Check interface.

For an example of how to build your own linter utility, please refer to the thrift-lint source.

Example checker

Here is an example of a checker utilising the MakeCheck() convenience function to ensure that fields are present in the file in the same order as their field numbers:

func CheckStructFieldOrder() thriftlint.Check {
  return thriftlint.MakeCheck("field.order", func(s *parser.Struct) (messages thriftlint.Messages) {
    fields := sortedFields(s.Fields)
    sort.Sort(fields)
    for i := 0; i < len(fields)-1; i++ {
      a := fields[i]
      b := fields[i+1]
      if a.Pos.Line > b.Pos.Line {
        messages.Warning(fields[i], "field %d and %d are out of order", a.ID, b.ID)
      }
    }
    return
  })
}

thrift-lint tool

A binary is included that can be used to perform basic linting with the builtin checks:

$ go get github.com/wy90021/thriftlint/cmd/thrift-lint
$ thrift-lint --help
usage: thrift-lint [<flags>] <sources>...

A linter for Thrift.

For details, please refer to https://github.com/wy90021/thriftlint

Flags:
      --help                Show context-sensitive help (also try --help-long
                            and --help-man).
  -I, --include=DIR ...     Include directories to search.
      --debug               Enable debug logging.
      --disable=LINTER ...  Linters to disable.
      --list                List linter checks.
      --errors              Only show errors.

Args:
  <sources>  Thrift sources to lint.

Documentation

Overview

Package thriftlint is an extensible Linter for Thrift files, written in Go.

New() takes a set of checks and options and creates a linter. The linter checks can then be applied to a set of files with .Lint(files...).

See the README for details.

Package linter lints Thrift files.

Actual implementations of linter checks are in the subpackage "checks".

Index

• Variables
• func Annotation(node interface{}, key, dflt string) string
• func AnnotationExists(node interface{}, key string) bool
• func Comment(v interface{}) []string
• func DotSuffix(pkg string) string
• func IsInitialism(s string) bool
• func LowerCamelCase(s string) string
• func LowerSnakeCase(s string) string
• func Parse(includeDirs []string, sources []string) (map[string]*parser.Thrift, error)
• func Pos(v interface{}) parser.Pos
• func Resolve(symbol string, file *parser.Thrift) interface{}
• func SplitSymbol(s string) []string
• func UpperCamelCase(s string) string
• func UpperSnakeCase(s string) string
• type Check
  • func MakeCheck(id string, checker interface{}) Check
• type Checks
  • func (c Checks) CloneAndDisable(prefixes ...string) Checks
  • func (c Checks) Has(prefix string) bool
• type Linter
  • func New(checks []Check, options ...Option) (*Linter, error)
  • func (l *Linter) Lint(sources []string) (Messages, error)
• type Message
• type Messages
  • func (w *Messages) Error(object interface{}, msg string, args ...interface{}) Messages
  • func (w *Messages) Warning(object interface{}, msg string, args ...interface{}) Messages
• type Option
  • func Disable(checks ...string) Option
  • func WithIncludeDirs(dirs ...string) Option
  • func WithLogger(logger logger) Option
• type Severity
  • func (s Severity) String() string

Variables

var (
	// BuiltinThriftTypes is a map of the basic builtin Thrift types. Useful in templates.
	BuiltinThriftTypes = map[string]bool{
		"bool":   true,
		"byte":   true,
		"i16":    true,
		"i32":    true,
		"i64":    true,
		"double": true,
		"string": true,
	}

	// BuiltinThriftCollections is the set of builtin collection types in Thrift.
	BuiltinThriftCollections = map[string]bool{
		"map":    true,
		"list":   true,
		"set":    true,
		"binary": true,
	}
)

var (
	TypeType = reflect.TypeOf(parser.Type{})

	ThriftType = reflect.TypeOf(parser.Thrift{})

	ServiceType = reflect.TypeOf(parser.Service{})
	MethodType  = reflect.TypeOf(parser.Method{})

	EnumType      = reflect.TypeOf(parser.Enum{})
	EnumValueType = reflect.TypeOf(parser.EnumValue{})

	StructType = reflect.TypeOf(parser.Struct{})
	FieldType  = reflect.TypeOf(parser.Field{})

	ConstantType = reflect.TypeOf(parser.Constant{})
	TypedefType  = reflect.TypeOf(parser.Typedef{})
)

Types and their supported annotations.

Functions

func Annotation

func Annotation(node interface{}, key, dflt string) string

Annotation returns the annotation value associated with "key" from the .Annotations field of a go-thrift AST node.

This will panic if node is not a struct with an Annotations field of the correct type.

func AnnotationExists

func AnnotationExists(node interface{}, key string) bool

AnnotationExists checks if an annotation is present at all.

func Comment

func Comment(v interface{}) []string

func DotSuffix

func DotSuffix(pkg string) string

Extract the suffix from a . separated string (ie. namespace). Useful for getting the package reference from a files namespace.

func IsInitialism

func IsInitialism(s string) bool

func LowerCamelCase

func LowerCamelCase(s string) string

LowerCamelCase converts a symbol to lowerCamelCase

func LowerSnakeCase

func LowerSnakeCase(s string) string

LowerSnakeCase converts a symbol to snake_case

func Parse

func Parse(includeDirs []string, sources []string) (map[string]*parser.Thrift, error)

Parse a set of .thrift source files into their corresponding ASTs.

func Pos

func Pos(v interface{}) parser.Pos

Attempt to extra positional information from a struct.

func Resolve

func Resolve(symbol string, file *parser.Thrift) interface{}

Resolve a symbol within a file to its type.

func SplitSymbol

func SplitSymbol(s string) []string

SplitSymbol splits an arbitrary symbol into parts. It accepts symbols in snake case and camel case, and correctly supports all-caps substrings.

eg. "some_snake_case_symbol" would become ["some", "snake", "case", "symbol"] and "someCamelCaseSymbol" would become ["some", "Camel", "Case", "Symbol"]

func UpperCamelCase

func UpperCamelCase(s string) string

UpperCamelCase converts a symbol to CamelCase

func UpperSnakeCase

func UpperSnakeCase(s string) string

UpperSnakeCase converts a symbol to UPPER_SNAKE_CASE

Types

type Check

type Check interface {
	// ID of the Check. Must be unique across all checks.
	//
	// IDs may be hierarchical, separated by a period. eg. "enum", "enum.values"
	ID() string
	// Checker returns the checking function.
	//
	// The checking function has the signature "func(...) Messages", where "..." is a sequence of
	// Thrift AST types that are matched against the current node's ancestors as the linter walks
	// the AST of each file.  "..." may also be "interface{}" in which case the checker function
	// will be called for each node in the AST.
	//
	// For example, the function:
	//
	//     func (s *parser.Struct, f *parser.Field) (messages Messages)
	//
	// Will match all each struct field, but not union fields.
	Checker() interface{}
}

Check implementations are used by the linter to check AST nodes.

func MakeCheck

func MakeCheck(id string, checker interface{}) Check

MakeCheck creates a stateless Check type from an ID and a checker function.

type Checks

type Checks []Check

Checks is a convenience wrapper around a slice of Checks.

func (Checks) CloneAndDisable

func (c Checks) CloneAndDisable(prefixes ...string) Checks

CloneAndDisable returns a copy of this Checks slice with all checks matching prefix disabled.

func (Checks) Has

func (c Checks) Has(prefix string) bool

Has returns true if the Checks slice contains any checks matching prefix.

type Linter

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

func New

func New(checks []Check, options ...Option) (*Linter, error)

New creates a new Linter.

func (*Linter) Lint

func (l *Linter) Lint(sources []string) (Messages, error)

Lint the given files.

type Message

type Message struct {
	// File that resulted in the message.
	File *parser.Thrift
	// ID of the Checker that generated this message.
	Checker  string
	Severity Severity
	Object   interface{}
	Message  string
}

Message represents a single linter message.

type Messages

type Messages []*Message

Messages is the set of messages each check should return.

Typically it will be used like so:

func MyCheck(...) (messages Messages) {
  messages.Warning(t, "some warning")
}

func (*Messages) Error

func (w *Messages) Error(object interface{}, msg string, args ...interface{}) Messages

Warning adds an error-level message to the Messages.

func (*Messages) Warning

func (w *Messages) Warning(object interface{}, msg string, args ...interface{}) Messages

Warning adds a warning-level message to the Messages.

type Option

type Option func(*Linter)

func Disable

func Disable(checks ...string) Option

Disable is an Option that disables the given checks.

func WithIncludeDirs

func WithIncludeDirs(dirs ...string) Option

WithIncludeDirs is an Option that sets the directories to use for searching when parsing Thrift includes.

func WithLogger

func WithLogger(logger logger) Option

WithLogger is an Option that sets the logger object used by the linter.

type Severity

type Severity int

Severity of a linter message.

const (
	Warning Severity = iota
	Error
)

Message severities.

func (Severity) String

func (s Severity) String() string