rules

Documentation

Index

• type Filter
• type Parser
  • func NewParser() *Parser
  • func (*Parser) Parse(filename string, r io.Reader) (*Set, error)
• type Rule
  • func (r *Rule) String() string
• type RuleKind
  • func CategorizeNode(n node.Node) RuleKind
• type ScopedSet
• type Set
  • func NewSet() *Set

Types

type Filter

type Filter struct {
	Type phpdoc.TypeExpr
}

Filter describes constraints that should be applied to a given phpgrep variable.

type Parser

type Parser struct{}

func NewParser

func NewParser() *Parser

func (*Parser) Parse

func (*Parser) Parse(filename string, r io.Reader) (*Set, error)

type Rule

type Rule struct {
	// Name tells whether this rule causes critical report.
	Name string

	// Matcher is an object that is used to check whether a given AST node
	// should trigger a warning that is associated with rule.
	Matcher *phpgrep.Matcher

	// Level is a severity level that is used during report generation.
	Level int

	// Message is a report text that is printed when this rule matches.
	Message string

	// Location is a phpgrep variable name that should be used as a warning location.
	// Empty string selects the root node.
	Location string

	// Path is a filter-like rule switcher.
	// A rule is only applied to a file that contains a Path as a substring in its name.
	Path string

	// Filters is a list of OR-connected filter sets.
	// Every filter set is a mapping of phpgrep variable to a filter.
	Filters []map[string]Filter
	// contains filtered or unexported fields
}

Rule is a dynamically-loaded linter rule.

A rule is called unnamed if no @name attribute is given. Unnamed rules receive auto-generated name that includes a rule file name and a line that defines that rule.

func (*Rule) String

func (r *Rule) String() string

String returns a rule printer representation.

type RuleKind

type RuleKind int

const (
	KindNone RuleKind = iota

	KindMethodCall
	KindFunctionCall
	KindStaticCall
	KindArray

	KindValueFetch
	KindCmp     // All binary comparison ops
	KindBinOp   // All binary ops except comparison ops
	KindUnaryOp // All unary-ish ops
	KindAssign  // All assignments
	KindCondOp  // All conditional expressions
	KindBranch  // All conditional statements
	KindScalar  // All scalar-like nodes
	KindConst   // All const fetching ops
	KindRequire
	KindLoop
	KindCast
	KindOther         // All remaining kinds that are not None
	KindOtherUnlikely // Second Other category, even less priority

)

All kinds of node categories.

See CategorizeNode to see how they are connected with particular node types.

func CategorizeNode

func CategorizeNode(n node.Node) RuleKind

CategorizeNode tries to associate a node with one of the known categories. If node can't be (yet?) categorized, returns KindNone.

Note that for some nodes we *want* to return KindNone, since matching engine can have a hard time trying to match them.

We try to categorize nodes in a way that predict which rules have higher chances to be used by the users. For examples, it's likely that function calls could be the most important pattern out there. With some other groups it's more or less shot in the dark. A better algorithm can be found later. Maybe we'll assign categories dynamically or map them 1-to-1 with nodes kind in future.

type ScopedSet

type ScopedSet struct {
	RulesByKind [_KindCount][]Rule
}

ScopedSet is a categorized rules collection. Categories help to assign a better execution strategy for a rule.

type Set

type Set struct {
	Any   *ScopedSet // Anywhere
	Root  *ScopedSet // Only outside of functions
	Local *ScopedSet // Only inside functions

	AlwaysAllowed  []string // All unnamed rules
	AlwaysCritical []string // Unnamed rules of warning or error level
}

Set is a result of rule file parsing.

func NewSet

func NewSet() *Set

NewSet returns a new empty rules set.