linter: refactored report functions (#1053)

Now at the heart of all the functions for creating reports
is a function that creates a report at a given location.

Report and ReportPHPDoc are now wrappers that convert node
and PHPDocLocation to Location for ReportLocation.

ReportByLine has been removed as it is no longer used and
can be replaced with ReportLocation.

Fixed error, if the warning was given on the last line in
the file, then the context line was empty.

A new ir.Location structure has been added.
ir.Location stores the shifts relative to the current line.
A new structure is needed since position.Position stores
line shifts relative to the beginning of the file, and not
relative to the current line, which is very inconvenient for
using ReportLocation.

src/ir/location.go

@@ -0,0 +1,20 @@
+package ir
+
+// Location stores the position of some element, where StartChar and EndChar
+// are offsets relative to the current line, as opposed to position.Position,
+// where the offset is relative to the beginning of the file.
+type Location struct {
+	StartLine int
+	EndLine   int
+	StartChar int
+	EndChar   int
+}
+
+func NewLocation(startLine int, endLine int, startChar int, endChar int) *Location {
+	return &Location{
+		StartLine: startLine,
+		EndLine:   endLine,
+		StartChar: startChar,
+		EndChar:   endChar,
+	}
+}

src/linter/custom.go

@@ -139,14 +139,24 @@ func (ctx *RootContext) ParsePHPDoc(doc string) phpdoc.Comment {
 }
 
 // Report records linter warning of specified level.
-// chechName is a key that identifies the "checker" (diagnostic name) that found
+// checkName is a key that identifies the "checker" (diagnostic name) that found
 // issue being reported.
 func (ctx *RootContext) Report(n ir.Node, level int, checkName, msg string, args ...interface{}) {
 	ctx.w.Report(n, level, checkName, msg, args...)
 }
 
-func (ctx *RootContext) ReportByLine(lineNumber, level int, checkName, msg string, args ...interface{}) {
-	ctx.w.ReportByLine(lineNumber, level, checkName, msg, args...)
+// ReportPHPDoc records linter warning in PHPDoc of specified level.
+// checkName is a key that identifies the "checker" (diagnostic name) that found
+// issue being reported.
+func (ctx *RootContext) ReportPHPDoc(phpDocLocation PHPDocLocation, level int, checkName, msg string, args ...interface{}) {
+	ctx.w.ReportPHPDoc(phpDocLocation, level, checkName, msg, args...)
+}
+
+// ReportLocation records linter warning in specified location of specified level.
+// checkName is a key that identifies the "checker" (diagnostic name) that found
+// issue being reported.
+func (ctx *RootContext) ReportLocation(location ir.Location, level int, checkName, msg string, args ...interface{}) {
+	ctx.w.ReportLocation(location, level, checkName, msg, args...)
 }
 
 // Scope returns variables declared at root level.
@@ -199,8 +209,18 @@ func (ctx *BlockContext) Report(n ir.Node, level int, checkName, msg string, arg
 	ctx.w.r.Report(n, level, checkName, msg, args...)
 }
 
-func (ctx *BlockContext) ReportByLine(lineNumber, level int, checkName, msg string, args ...interface{}) {
-	ctx.w.r.ReportByLine(lineNumber, level, checkName, msg, args...)
+// ReportPHPDoc records linter warning in PHPDoc of specified level.
+// checkName is a key that identifies the "checker" (diagnostic name) that found
+// issue being reported.
+func (ctx *BlockContext) ReportPHPDoc(phpDocLocation PHPDocLocation, level int, checkName, msg string, args ...interface{}) {
+	ctx.w.r.ReportPHPDoc(phpDocLocation, level, checkName, msg, args...)
+}
+
+// ReportLocation records linter warning in specified location of specified level.
+// checkName is a key that identifies the "checker" (diagnostic name) that found
+// issue being reported.
+func (ctx *BlockContext) ReportLocation(location ir.Location, level int, checkName, msg string, args ...interface{}) {
+	ctx.w.r.ReportLocation(location, level, checkName, msg, args...)
 }
 
 // Scope returns variables declared in this block.

src/linter/phpdoc_util.go

@@ -17,19 +17,41 @@ type PHPDocLocation struct {
 	Line      int
 	Field     int
 	WholeLine bool
+	// RelativeLine is set if the line number is relative to the
+	// given node; otherwise, the line number is considered to be
+	// absolute and can be used directly.
+	RelativeLine bool
 }
 
 func PHPDocLine(n ir.Node, line int) PHPDocLocation {
 	return PHPDocLocation{
-		Node:      n,
+		Node:         n,
+		Line:         line,
+		WholeLine:    true,
+		RelativeLine: true,
+	}
+}
+
+func PHPDocAbsoluteLine(line int) PHPDocLocation {
+	return PHPDocLocation{
+		Node:      nil,
 		Line:      line,
 		WholeLine: true,
 	}
 }
 
 func PHPDocLineField(n ir.Node, line int, field int) PHPDocLocation {
 	return PHPDocLocation{
-		Node:  n,
+		Node:         n,
+		Line:         line,
+		Field:        field,
+		RelativeLine: true,
+	}
+}
+
+func PHPDocAbsoluteLineField(line int, field int) PHPDocLocation {
+	return PHPDocLocation{
+		Node:  nil,
 		Line:  line,
 		Field: field,
 	}