blob: 0667a08221fc440dac5617153c7b997251a8c614 [file] [log] [blame]
// 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 (
// 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:
// 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/"
// 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/" -> "src/foo/".
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