tools/staticanalysis/staticanalysis.go - fuchsia - Git at Google

 // Copyright 2021 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.

 package staticanalysis

 import (
 	"context"
 	"fmt"
 	"path"
 	"path/filepath"
 	"strings"
 )

 // Analyzer is the interface that must be implemented for each linter/formatter
 // that integrates with this tool.
 type Analyzer interface {
 	// Analyze validates a single source file, returning any findings.
 	//
 	// The `path` argument is relative to the checkout root.
 	Analyze(ctx context.Context, path string) ([]*Finding, error)
 }

 // A suggested replacement.
 //
 // The replacement should be for one continuous section of a file.
 type Replacement struct {
 	// Path to the file for this replacement.
 	//
 	// An empty string indicates the commit message.
 	Path string `json:"path"`

 	// A replacement string.
 	Replacement string `json:"replacement"`

 	// A continuous section of the file to replace. Required.
 	StartLine int `json:"start_line"` // 1-based, inclusive.
 	EndLine   int `json:"end_line"`   // 1-based, inclusive.
 	StartChar int `json:"start_char"` // 0-based, inclusive.
 	EndChar   int `json:"end_char"`   // 0-based, exclusive.
 }

 // A suggestion is associated with a single finding and contains a list of
 // possible replacement texts for the text that the finding covers.
 type Suggestion struct {
 	Description string `json:"description"`

 	Replacements []Replacement `json:"replacements"`
 }

 // Finding is the common schema that all linters' and formatters' outputs must
 // be converted to in order to be compatible with this tool. Each Finding that
 // applies to lines that are affected by the change under test may be posted as
 // a Gerrit comment.
 //
 // Mirrors the Tricium comment schema:
 // https://chromium.googlesource.com/infra/infra/+/3b0abf2fb146af025440a48e1f7423595b1a5bfb/go/src/infra/tricium/api/v1/data.proto#122
 //
 // TODO(olivernewman): Make this a proper proto file that gets copied into the
 // recipes repository.
 type Finding struct {
 	// Category is the text that will be used as the header of the Gerrit
 	// comment emitted for this finding.
 	//
 	// Should be of the form "<tool name>/<error level>/<error type>" for
 	// linters, e.g. "Clippy/warning/bool_comparison", or just the name of the
 	// tool for things like auto-formatters, e.g. "Gofmt".
 	//
 	// Required.
 	Category string `json:"category"`

 	// Message is a human-readable description of the finding, e.g. "variable
 	// foo is not defined".
 	//
 	// Required.
 	Message string `json:"message"`

 	// Path is the path to the file within a fuchsia checkout, using forward
 	// slashes as delimiters, e.g. "src/foo/bar.cc"
 	//
 	// If omitted, the finding will apply to the change's commit message.
 	Path string `json:"path"`

 	// StartLine is the starting line of the chunk of the file that the finding
 	// applies to (1-indexed, inclusive).
 	//
 	// If omitted, the finding will apply to the entire file and a top-level
 	// file comment will be emitted.
 	StartLine int `json:"start_line,omitempty"`

 	// EndLine is the ending line of the chunk of the file that the finding
 	// applies to (1-indexed, inclusive).
 	//
 	// If set, must be greater than or equal to StartLine.
 	//
 	// If omitted, Endline is assumed to be equal to StartLine.
 	EndLine int `json:"end_line,omitempty"`

 	// StartChar is the index of the first character within StartLine that the
 	// finding applies to (0-indexed, inclusive).
 	//
 	// If omitted, the finding will apply to the entire line.
 	StartChar int `json:"start_char,omitempty"`

 	// EndChar is the index of the last character within EndLine that the
 	// finding applies to (0-indexed, exclusive).
 	//
 	// Required if StartChar is specified. If StartLine==EndLine, EndChar must
 	// be greater than StartChar.
 	EndChar int `json:"end_char,omitempty"`

 	// Suggestions is a list of possible strings that could replace the text
 	// highlighted by the finding.
 	//
 	// If set, all of StartLine, EndLine, StartChar, and EndChar must be
 	// specified.
 	Suggestions []Suggestion `json:"suggestions,omitempty"`
 }

 // Normalize makes a best effort at updating invalid/inconsistent fields to be
 // sensible, returning an error if there are any field values that are invalid
 // and for which a valid value cannot be determined.
 //
 // In an ideal world we would *validate* each analyzer finding rather than
 // emitting different values from what the analyzers produce. But that would
 // require potentially tedious and repetitive normalization logic in each
 // analyzer, so instead we centralize the normalization logic here to make it
 // easier to write new analyzers.
 func (f *Finding) Normalize() error {
 	if f.Category == "" {
 		return fmt.Errorf("category must be set for finding: %#+v", f)
 	}

 	if f.Message == "" {
 		return fmt.Errorf("message must be set for finding: %#+v", f)
 	}

 	// It's okay for Path to not be set, in which case the finding will be
 	// interpreted as applying to the entire change.
 	if f.Path != "" {
 		if path.IsAbs(f.Path) || strings.HasPrefix(f.Path, "..") || f.Path != path.Clean(f.Path) {
 			return fmt.Errorf("path must be a clean source-relative path for finding: %#+v", f)
 		}
 	}

 	if f.StartLine > 0 {
 		if f.EndLine == 0 {
 			// If unset, update EndLine to be equal to StartLine.
 			f.EndLine = f.StartLine
 		}
 		if f.StartLine == f.EndLine && f.StartChar > 0 && f.StartChar == f.EndChar {
 			// Fix the common case where an analyzer emits StartChar and EndChar
 			// of the same value to highlight a single-character.
 			f.EndChar = f.StartChar + 1
 		}

 		if f.StartLine > f.EndLine || (f.StartLine == f.EndLine && f.StartChar > 0 && f.StartChar >= f.EndChar) {
 			return fmt.Errorf("(start_line, start_char) must be before (end_line, end_char) for finding: %#+v", f)
 		}
 	} else if f.EndLine > 0 || f.StartChar > 0 || f.EndChar > 0 {
 		return fmt.Errorf("start_line is unexpectedly unset for finding: %#+v", f)
 	}

 	if len(f.Suggestions) > 0 && (f.StartLine < 1 || f.EndLine < 1 || f.StartChar < 0 || f.EndChar <= 0) {
 		return fmt.Errorf("a finding with suggestions must have a fully specified span: %#+v", f)
 	}

 	for _, suggestion := range f.Suggestions {
 		for _, r := range suggestion.Replacements {
 			if r.StartLine < 1 || r.EndLine < 1 || r.StartChar < 0 || r.EndChar < 0 {
 				return fmt.Errorf("a suggested replacement must have a fully specified span: %#+v", r)
 			}
 			// StartChar==EndChar is allowed for a replacement span because a
 			// replacement might just insert text without replacing any
 			// pre-existing text.
 			if r.StartLine > r.EndLine || (r.StartLine == r.EndLine && r.StartChar > r.EndChar) {
 				return fmt.Errorf("(start_line, start_char) must be before (end_line, end_char) for replacement in finding: %#+v", f)
 			}
 		}
 	}

 	return nil
 }

 // BuildPathToCheckoutPath converts a path relative to the build directory into
 // a source-relative path with platform-agnostic separators.
 //
 // E.g. "../../src/foo/bar.py" -> "src/foo/bar.py".
 func BuildPathToCheckoutPath(path, buildDir, checkoutDir string) (string, error) {
 	absPath := filepath.Clean(filepath.Join(buildDir, path))
 	path, err := filepath.Rel(checkoutDir, absPath)
 	if err != nil {
 		return "", err
 	}
 	return filepath.ToSlash(path), nil
 }
	// Copyright 2021 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.

	package staticanalysis

	import (
	"context"
	"fmt"
	"path"
	"path/filepath"
	"strings"
	)

	// Analyzer is the interface that must be implemented for each linter/formatter
	// that integrates with this tool.
	type Analyzer interface {
	// Analyze validates a single source file, returning any findings.
	//
	// The `path` argument is relative to the checkout root.
	Analyze(ctx context.Context, path string) ([]*Finding, error)
	}

	// A suggested replacement.
	//
	// The replacement should be for one continuous section of a file.
	type Replacement struct {
	// Path to the file for this replacement.
	//
	// An empty string indicates the commit message.
	Path string `json:"path"`

	// A replacement string.
	Replacement string `json:"replacement"`

	// A continuous section of the file to replace. Required.
	StartLine int `json:"start_line"` // 1-based, inclusive.
	EndLine int `json:"end_line"` // 1-based, inclusive.
	StartChar int `json:"start_char"` // 0-based, inclusive.
	EndChar int `json:"end_char"` // 0-based, exclusive.
	}

	// A suggestion is associated with a single finding and contains a list of
	// possible replacement texts for the text that the finding covers.
	type Suggestion struct {
	Description string `json:"description"`

	Replacements []Replacement `json:"replacements"`
	}

	// Finding is the common schema that all linters' and formatters' outputs must
	// be converted to in order to be compatible with this tool. Each Finding that
	// applies to lines that are affected by the change under test may be posted as
	// a Gerrit comment.
	//
	// Mirrors the Tricium comment schema:
	// https://chromium.googlesource.com/infra/infra/+/3b0abf2fb146af025440a48e1f7423595b1a5bfb/go/src/infra/tricium/api/v1/data.proto#122
	//
	// TODO(olivernewman): Make this a proper proto file that gets copied into the
	// recipes repository.
	type Finding struct {
	// Category is the text that will be used as the header of the Gerrit
	// comment emitted for this finding.
	//
	// Should be of the form "<tool name>/<error level>/<error type>" for
	// linters, e.g. "Clippy/warning/bool_comparison", or just the name of the
	// tool for things like auto-formatters, e.g. "Gofmt".
	//
	// Required.
	Category string `json:"category"`

	// Message is a human-readable description of the finding, e.g. "variable
	// foo is not defined".
	//
	// Required.
	Message string `json:"message"`

	// Path is the path to the file within a fuchsia checkout, using forward
	// slashes as delimiters, e.g. "src/foo/bar.cc"
	//
	// If omitted, the finding will apply to the change's commit message.
	Path string `json:"path"`

	// StartLine is the starting line of the chunk of the file that the finding
	// applies to (1-indexed, inclusive).
	//
	// If omitted, the finding will apply to the entire file and a top-level
	// file comment will be emitted.
	StartLine int `json:"start_line,omitempty"`

	// EndLine is the ending line of the chunk of the file that the finding
	// applies to (1-indexed, inclusive).
	//
	// If set, must be greater than or equal to StartLine.
	//
	// If omitted, Endline is assumed to be equal to StartLine.
	EndLine int `json:"end_line,omitempty"`

	// StartChar is the index of the first character within StartLine that the
	// finding applies to (0-indexed, inclusive).
	//
	// If omitted, the finding will apply to the entire line.
	StartChar int `json:"start_char,omitempty"`

	// EndChar is the index of the last character within EndLine that the
	// finding applies to (0-indexed, exclusive).
	//
	// Required if StartChar is specified. If StartLine==EndLine, EndChar must
	// be greater than StartChar.
	EndChar int `json:"end_char,omitempty"`

	// Suggestions is a list of possible strings that could replace the text
	// highlighted by the finding.
	//
	// If set, all of StartLine, EndLine, StartChar, and EndChar must be
	// specified.
	Suggestions []Suggestion `json:"suggestions,omitempty"`
	}

	// Normalize makes a best effort at updating invalid/inconsistent fields to be
	// sensible, returning an error if there are any field values that are invalid
	// and for which a valid value cannot be determined.
	//
	// In an ideal world we would validate each analyzer finding rather than
	// emitting different values from what the analyzers produce. But that would
	// require potentially tedious and repetitive normalization logic in each
	// analyzer, so instead we centralize the normalization logic here to make it
	// easier to write new analyzers.
	func (f *Finding) Normalize() error {
	if f.Category == "" {
	return fmt.Errorf("category must be set for finding: %#+v", f)
	}

	if f.Message == "" {
	return fmt.Errorf("message must be set for finding: %#+v", f)
	}

	// It's okay for Path to not be set, in which case the finding will be
	// interpreted as applying to the entire change.
	if f.Path != "" {
	if path.IsAbs(f.Path) \|\| strings.HasPrefix(f.Path, "..") \|\| f.Path != path.Clean(f.Path) {
	return fmt.Errorf("path must be a clean source-relative path for finding: %#+v", f)
	}
	}

	if f.StartLine > 0 {
	if f.EndLine == 0 {
	// If unset, update EndLine to be equal to StartLine.
	f.EndLine = f.StartLine
	}
	if f.StartLine == f.EndLine && f.StartChar > 0 && f.StartChar == f.EndChar {
	// Fix the common case where an analyzer emits StartChar and EndChar
	// of the same value to highlight a single-character.
	f.EndChar = f.StartChar + 1
	}

	if f.StartLine > f.EndLine \|\| (f.StartLine == f.EndLine && f.StartChar > 0 && f.StartChar >= f.EndChar) {
	return fmt.Errorf("(start_line, start_char) must be before (end_line, end_char) for finding: %#+v", f)
	}
	} else if f.EndLine > 0 \|\| f.StartChar > 0 \|\| f.EndChar > 0 {
	return fmt.Errorf("start_line is unexpectedly unset for finding: %#+v", f)
	}

	if len(f.Suggestions) > 0 && (f.StartLine < 1 \|\| f.EndLine < 1 \|\| f.StartChar < 0 \|\| f.EndChar <= 0) {
	return fmt.Errorf("a finding with suggestions must have a fully specified span: %#+v", f)
	}

	for _, suggestion := range f.Suggestions {
	for _, r := range suggestion.Replacements {
	if r.StartLine < 1 \|\| r.EndLine < 1 \|\| r.StartChar < 0 \|\| r.EndChar < 0 {
	return fmt.Errorf("a suggested replacement must have a fully specified span: %#+v", r)
	}
	// StartChar==EndChar is allowed for a replacement span because a
	// replacement might just insert text without replacing any
	// pre-existing text.
	if r.StartLine > r.EndLine \|\| (r.StartLine == r.EndLine && r.StartChar > r.EndChar) {
	return fmt.Errorf("(start_line, start_char) must be before (end_line, end_char) for replacement in finding: %#+v", f)
	}
	}
	}

	return nil
	}

	// BuildPathToCheckoutPath converts a path relative to the build directory into
	// a source-relative path with platform-agnostic separators.
	//
	// E.g. "../../src/foo/bar.py" -> "src/foo/bar.py".
	func BuildPathToCheckoutPath(path, buildDir, checkoutDir string) (string, error) {
	absPath := filepath.Clean(filepath.Join(buildDir, path))
	path, err := filepath.Rel(checkoutDir, absPath)
	if err != nil {
	return "", err
	}
	return filepath.ToSlash(path), nil
	}