warn

Documentation

Overview

Package warn implements functions that generate warnings for BUILD files.

Index

• Constants
• Variables
• func DisabledWarning(f *build.File, findingLine int, warning string) bool
• func FixWarnings(f *build.File, enabledWarnings []string, verbose bool, fileReader *FileReader)
• type FileReader
  • func NewFileReader(readFile func(string) ([]byte, error)) *FileReader
  • func (fr *FileReader) GetFile(pkg, label string) *build.File
• type Finding
  • func FileWarnings(f *build.File, enabledWarnings []string, formatted *[]byte, mode LintMode, ...) []*Finding
• type LintMode
• type LinterFinding
  • func NotLoadedFunctionUsageCheck(f *build.File, globals []string, loadFrom string) []*LinterFinding
• type LinterReplacement
• type Replacement
• type Type
  • func (t Type) String() string

Constants

const FunctionLengthDocstringThreshold = 5

FunctionLengthDocstringThreshold is a limit for a function size (in statements), above which a public function is required to have a docstring.

Variables

var AllWarnings = collectAllWarnings()

AllWarnings is the list of all available warnings.

var DefaultWarnings = collectDefaultWarnings()

DefaultWarnings is the list of all warnings that should be used inside google3

var FileWarningMap = map[string]func(f *build.File) []*LinterFinding{
	"attr-cfg":                  attrConfigurationWarning,
	"attr-license":              attrLicenseWarning,
	"attr-non-empty":            attrNonEmptyWarning,
	"attr-output-default":       attrOutputDefaultWarning,
	"attr-single-file":          attrSingleFileWarning,
	"build-args-kwargs":         argsKwargsInBuildFilesWarning,
	"bzl-visibility":            bzlVisibilityWarning,
	"confusing-name":            confusingNameWarning,
	"constant-glob":             constantGlobWarning,
	"ctx-actions":               ctxActionsWarning,
	"ctx-args":                  contextArgsAPIWarning,
	"depset-items":              depsetItemsWarning,
	"depset-iteration":          depsetIterationWarning,
	"depset-union":              depsetUnionWarning,
	"dict-concatenation":        dictionaryConcatenationWarning,
	"duplicated-name":           duplicatedNameWarning,
	"filetype":                  fileTypeWarning,
	"function-docstring":        functionDocstringWarning,
	"function-docstring-header": functionDocstringHeaderWarning,
	"function-docstring-args":   functionDocstringArgsWarning,
	"function-docstring-return": functionDocstringReturnWarning,
	"git-repository":            nativeGitRepositoryWarning,
	"http-archive":              nativeHTTPArchiveWarning,
	"integer-division":          integerDivisionWarning,
	"keyword-positional-params": keywordPositionalParametersWarning,
	"list-append":               listAppendWarning,
	"load":                      unusedLoadWarning,
	"load-on-top":               loadOnTopWarning,
	"module-docstring":          moduleDocstringWarning,
	"name-conventions":          nameConventionsWarning,
	"native-android":            nativeAndroidRulesWarning,
	"native-build":              nativeInBuildFilesWarning,
	"native-cc":                 nativeCcRulesWarning,
	"native-java":               nativeJavaRulesWarning,
	"native-package":            nativePackageWarning,
	"native-proto":              nativeProtoRulesWarning,
	"native-py":                 nativePyRulesWarning,
	"no-effect":                 noEffectWarning,
	"output-group":              outputGroupWarning,
	"out-of-order-load":         outOfOrderLoadWarning,
	"overly-nested-depset":      overlyNestedDepsetWarning,
	"package-name":              packageNameWarning,
	"package-on-top":            packageOnTopWarning,
	"print":                     printWarning,
	"provider-params":           providerParamsWarning,
	"redefined-variable":        redefinedVariableWarning,
	"repository-name":           repositoryNameWarning,
	"rule-impl-return":          ruleImplReturnWarning,
	"return-value":              missingReturnValueWarning,
	"same-origin-load":          sameOriginLoadWarning,
	"skylark-comment":           skylarkCommentWarning,
	"skylark-docstring":         skylarkDocstringWarning,
	"string-iteration":          stringIterationWarning,
	"uninitialized":             uninitializedVariableWarning,
	"unreachable":               unreachableStatementWarning,
	"unsorted-dict-items":       unsortedDictItemsWarning,
	"unused-variable":           unusedVariableWarning,
}

FileWarningMap lists the warnings that run on the whole file.

var MultiFileWarningMap = map[string]func(f *build.File, fileReader *FileReader) []*LinterFinding{
	"deprecated-function": deprecatedFunctionWarning,
	"unnamed-macro":       unnamedMacroWarning,
}

MultiFileWarningMap lists the warnings that run on the whole file, but may use other files.

var RuleWarningMap = map[string]func(call *build.CallExpr, pkg string) *LinterFinding{
	"positional-args": positionalArgumentsWarning,
}

RuleWarningMap lists the warnings that run on a single rule. These warnings run only on BUILD files (not bzl files).

Functions

func DisabledWarning

func DisabledWarning(f *build.File, findingLine int, warning string) bool

DisabledWarning checks if the warning was disabled by a comment. The comment format is buildozer: disable=<warning>

func FixWarnings

func FixWarnings(f *build.File, enabledWarnings []string, verbose bool, fileReader *FileReader)

FixWarnings fixes all warnings that can be fixed automatically.

Types

type FileReader

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

FileReader is a class that can read an arbitrary Starlark file from the repository and cache the results.

func NewFileReader

func NewFileReader(readFile func(string) ([]byte, error)) *FileReader

NewFileReader creates and initializes a FileReader instance with a custom readFile function that can read an arbitrary file in the repository using a path relative to the workspace root (OS-independent, with forward slashes).

func (*FileReader) GetFile

func (fr *FileReader) GetFile(pkg, label string) *build.File

GetFile reads a Starlark file from the repository or the cache. Returns nil if the file is not found or not valid.

type Finding

type Finding struct {
	File        *build.File
	Start       build.Position
	End         build.Position
	Category    string
	Message     string
	URL         string
	Actionable  bool
	Replacement *Replacement
}

A Finding is a warning reported by the analyzer. It may contain an optional suggested fix.

func FileWarnings

func FileWarnings(f *build.File, enabledWarnings []string, formatted *[]byte, mode LintMode, fileReader *FileReader) []*Finding

FileWarnings returns a list of all warnings found in the file.

type LintMode

type LintMode int

LintMode is an enum representing a linter mode. Can be either "warn", "fix", or "suggest"

const (
	// ModeWarn means only warnings should be returned for each finding.
	ModeWarn LintMode = iota
	// ModeFix means that all warnings that can be fixed automatically should be fixed and
	// no warnings should be returned for them.
	ModeFix
	// ModeSuggest means that automatic fixes shouldn't be applied, but instead corresponding
	// suggestions should be attached to all warnings that can be fixed automatically.
	ModeSuggest
)

type LinterFinding

type LinterFinding struct {
	Start       build.Position
	End         build.Position
	Message     string
	URL         string
	Replacement []LinterReplacement
}

LinterFinding is a low-level warning reported by single linter/fixer functions.

func NotLoadedFunctionUsageCheck

func NotLoadedFunctionUsageCheck(f *build.File, globals []string, loadFrom string) []*LinterFinding

NotLoadedFunctionUsageCheck checks whether there's a usage of a given not imported function in the file and adds a load statement if necessary.

type LinterReplacement

type LinterReplacement struct {
	Old *build.Expr
	New build.Expr
}

LinterReplacement is a low-level object returned by single fixer functions.

type Replacement

type Replacement struct {
	Description string
	Start       int
	End         int
	Content     string
}

A Replacement is a suggested fix. Text between Start and End should be replaced with Content.

type Type

type Type int

Type describes an expression type in Starlark.

const (
	Unknown Type = iota
	Bool
	Ctx
	CtxActions
	CtxActionsArgs
	Depset
	Dict
	Int
	None
	String
	List
)

List of known types

func (Type) String

func (t Type) String() string