Giant blob of minor changes

[dotfiles/.git] / .config / coc / extensions / coc-go-data / tools / pkg / mod / golang.org / x / tools@v0.0.0-20201105173854-bc9fc8d8c4bc / go / analysis / analysis.go

package analysis

import (
        "flag"
        "fmt"
        "go/ast"
        "go/token"
        "go/types"
        "reflect"

        "golang.org/x/tools/internal/analysisinternal"
)

// An Analyzer describes an analysis function and its options.
type Analyzer struct {
        // The Name of the analyzer must be a valid Go identifier
        // as it may appear in command-line flags, URLs, and so on.
        Name string

        // Doc is the documentation for the analyzer.
        // The part before the first "\n\n" is the title
        // (no capital or period, max ~60 letters).
        Doc string

        // Flags defines any flags accepted by the analyzer.
        // The manner in which these flags are exposed to the user
        // depends on the driver which runs the analyzer.
        Flags flag.FlagSet

        // Run applies the analyzer to a package.
        // It returns an error if the analyzer failed.
        //
        // On success, the Run function may return a result
        // computed by the Analyzer; its type must match ResultType.
        // The driver makes this result available as an input to
        // another Analyzer that depends directly on this one (see
        // Requires) when it analyzes the same package.
        //
        // To pass analysis results between packages (and thus
        // potentially between address spaces), use Facts, which are
        // serializable.
        Run func(*Pass) (interface{}, error)

        // RunDespiteErrors allows the driver to invoke
        // the Run method of this analyzer even on a
        // package that contains parse or type errors.
        RunDespiteErrors bool

        // Requires is a set of analyzers that must run successfully
        // before this one on a given package. This analyzer may inspect
        // the outputs produced by each analyzer in Requires.
        // The graph over analyzers implied by Requires edges must be acyclic.
        //
        // Requires establishes a "horizontal" dependency between
        // analysis passes (different analyzers, same package).
        Requires []*Analyzer

        // ResultType is the type of the optional result of the Run function.
        ResultType reflect.Type

        // FactTypes indicates that this analyzer imports and exports
        // Facts of the specified concrete types.
        // An analyzer that uses facts may assume that its import
        // dependencies have been similarly analyzed before it runs.
        // Facts must be pointers.
        //
        // FactTypes establishes a "vertical" dependency between
        // analysis passes (same analyzer, different packages).
        FactTypes []Fact
}

func (a *Analyzer) String() string { return a.Name }

func init() {
        // Set the analysisinternal functions to be able to pass type errors
        // to the Pass type without modifying the go/analysis API.
        analysisinternal.SetTypeErrors = func(p interface{}, errors []types.Error) {
                p.(*Pass).typeErrors = errors
        }
        analysisinternal.GetTypeErrors = func(p interface{}) []types.Error {
                return p.(*Pass).typeErrors
        }
}

// A Pass provides information to the Run function that
// applies a specific analyzer to a single Go package.
//
// It forms the interface between the analysis logic and the driver
// program, and has both input and an output components.
//
// As in a compiler, one pass may depend on the result computed by another.
//
// The Run function should not call any of the Pass functions concurrently.
type Pass struct {
        Analyzer *Analyzer // the identity of the current analyzer

        // syntax and type information
        Fset         *token.FileSet // file position information
        Files        []*ast.File    // the abstract syntax tree of each file
        OtherFiles   []string       // names of non-Go files of this package
        IgnoredFiles []string       // names of ignored source files in this package
        Pkg          *types.Package // type information about the package
        TypesInfo    *types.Info    // type information about the syntax trees
        TypesSizes   types.Sizes    // function for computing sizes of types

        // Report reports a Diagnostic, a finding about a specific location
        // in the analyzed source code such as a potential mistake.
        // It may be called by the Run function.
        Report func(Diagnostic)

        // ResultOf provides the inputs to this analysis pass, which are
        // the corresponding results of its prerequisite analyzers.
        // The map keys are the elements of Analysis.Required,
        // and the type of each corresponding value is the required
        // analysis's ResultType.
        ResultOf map[*Analyzer]interface{}

        // -- facts --

        // ImportObjectFact retrieves a fact associated with obj.
        // Given a value ptr of type *T, where *T satisfies Fact,
        // ImportObjectFact copies the value to *ptr.
        //
        // ImportObjectFact panics if called after the pass is complete.
        // ImportObjectFact is not concurrency-safe.
        ImportObjectFact func(obj types.Object, fact Fact) bool

        // ImportPackageFact retrieves a fact associated with package pkg,
        // which must be this package or one of its dependencies.
        // See comments for ImportObjectFact.
        ImportPackageFact func(pkg *types.Package, fact Fact) bool

        // ExportObjectFact associates a fact of type *T with the obj,
        // replacing any previous fact of that type.
        //
        // ExportObjectFact panics if it is called after the pass is
        // complete, or if obj does not belong to the package being analyzed.
        // ExportObjectFact is not concurrency-safe.
        ExportObjectFact func(obj types.Object, fact Fact)

        // ExportPackageFact associates a fact with the current package.
        // See comments for ExportObjectFact.
        ExportPackageFact func(fact Fact)

        // AllPackageFacts returns a new slice containing all package facts of the analysis's FactTypes
        // in unspecified order.
        // WARNING: This is an experimental API and may change in the future.
        AllPackageFacts func() []PackageFact

        // AllObjectFacts returns a new slice containing all object facts of the analysis's FactTypes
        // in unspecified order.
        // WARNING: This is an experimental API and may change in the future.
        AllObjectFacts func() []ObjectFact

        // typeErrors contains types.Errors that are associated with the pkg.
        typeErrors []types.Error

        /* Further fields may be added in future. */
        // For example, suggested or applied refactorings.
}

// PackageFact is a package together with an associated fact.
// WARNING: This is an experimental API and may change in the future.
type PackageFact struct {
        Package *types.Package
        Fact    Fact
}

// ObjectFact is an object together with an associated fact.
// WARNING: This is an experimental API and may change in the future.
type ObjectFact struct {
        Object types.Object
        Fact   Fact
}

// Reportf is a helper function that reports a Diagnostic using the
// specified position and formatted error message.
func (pass *Pass) Reportf(pos token.Pos, format string, args ...interface{}) {
        msg := fmt.Sprintf(format, args...)
        pass.Report(Diagnostic{Pos: pos, Message: msg})
}

// The Range interface provides a range. It's equivalent to and satisfied by
// ast.Node.
type Range interface {
        Pos() token.Pos // position of first character belonging to the node
        End() token.Pos // position of first character immediately after the node
}

// ReportRangef is a helper function that reports a Diagnostic using the
// range provided. ast.Node values can be passed in as the range because
// they satisfy the Range interface.
func (pass *Pass) ReportRangef(rng Range, format string, args ...interface{}) {
        msg := fmt.Sprintf(format, args...)
        pass.Report(Diagnostic{Pos: rng.Pos(), End: rng.End(), Message: msg})
}

func (pass *Pass) String() string {
        return fmt.Sprintf("%s@%s", pass.Analyzer.Name, pass.Pkg.Path())
}

// A Fact is an intermediate fact produced during analysis.
//
// Each fact is associated with a named declaration (a types.Object) or
// with a package as a whole. A single object or package may have
// multiple associated facts, but only one of any particular fact type.
//
// A Fact represents a predicate such as "never returns", but does not
// represent the subject of the predicate such as "function F" or "package P".
//
// Facts may be produced in one analysis pass and consumed by another
// analysis pass even if these are in different address spaces.
// If package P imports Q, all facts about Q produced during
// analysis of that package will be available during later analysis of P.
// Facts are analogous to type export data in a build system:
// just as export data enables separate compilation of several passes,
// facts enable "separate analysis".
//
// Each pass (a, p) starts with the set of facts produced by the
// same analyzer a applied to the packages directly imported by p.
// The analysis may add facts to the set, and they may be exported in turn.
// An analysis's Run function may retrieve facts by calling
// Pass.Import{Object,Package}Fact and update them using
// Pass.Export{Object,Package}Fact.
//
// A fact is logically private to its Analysis. To pass values
// between different analyzers, use the results mechanism;
// see Analyzer.Requires, Analyzer.ResultType, and Pass.ResultOf.
//
// A Fact type must be a pointer.
// Facts are encoded and decoded using encoding/gob.
// A Fact may implement the GobEncoder/GobDecoder interfaces
// to customize its encoding. Fact encoding should not fail.
//
// A Fact should not be modified once exported.
type Fact interface {
        AFact() // dummy method to avoid type errors
}