api-linter: github.com/googleapis/api-linter/lint Index | Files

package lint

import "github.com/googleapis/api-linter/lint"

Package lint provides lint functions for Google APIs that register rules and user configurations, apply those rules to a lint request, and produce lint results.

Index

Package Files

config.go lint.go problem.go response.go rule.go rule_aliases.go rule_enabled.go rule_groups.go rule_name.go rule_registry.go rule_urls.go

type Config Uses

type Config struct {
    IncludedPaths []string `json:"included_paths" yaml:"included_paths"`
    ExcludedPaths []string `json:"excluded_paths" yaml:"excluded_paths"`
    EnabledRules  []string `json:"enabled_rules" yaml:"enabled_rules"`
    DisabledRules []string `json:"disabled_rules" yaml:"disabled_rules"`
}

Config stores rule configurations for certain files that the file path must match any of the included paths but none of the excluded ones.

type Configs Uses

type Configs []Config

Configs determine if a rule is enabled or not on a file path.

func ReadConfigsFromFile Uses

func ReadConfigsFromFile(path string) (Configs, error)

ReadConfigsFromFile reads Configs from a file. It supports JSON(.json) and YAML(.yaml or .yml) files.

func ReadConfigsJSON Uses

func ReadConfigsJSON(f io.Reader) (Configs, error)

ReadConfigsJSON reads Configs from a JSON file.

func ReadConfigsYAML Uses

func ReadConfigsYAML(f io.Reader) (Configs, error)

ReadConfigsYAML reads Configs from a JSON file.

func (Configs) IsRuleEnabled Uses

func (configs Configs) IsRuleEnabled(rule string, path string) bool

IsRuleEnabled returns true if a rule is enabled by the configs.

type DescriptorRule Uses

type DescriptorRule struct {
    Name RuleName

    // LintDescriptor accepts a generic descriptor and lints it.
    //
    // Note: Unless the descriptor is typecast to a more specific type,
    // only a subset of methods are available to it.
    LintDescriptor func(desc.Descriptor) []Problem

    // OnlyIf accepts a Descriptor and determines whether this rule
    // is applicable.
    OnlyIf func(desc.Descriptor) bool
    // contains filtered or unexported fields
}

DescriptorRule defines a lint rule that is run on every descriptor in the file (but not the file itself).

func (*DescriptorRule) GetName Uses

func (r *DescriptorRule) GetName() RuleName

GetName returns the name of the rule.

func (*DescriptorRule) Lint Uses

func (r *DescriptorRule) Lint(fd *desc.FileDescriptor) []Problem

Lint visits every descriptor in the file and runs `LintDescriptor`.

It visits every service, method, message, field, enum, and enum value. This order is not guaranteed. It does NOT visit the file itself.

type EnumRule Uses

type EnumRule struct {
    Name RuleName

    // LintEnum accepts a EnumDescriptor and lints it.
    LintEnum func(*desc.EnumDescriptor) []Problem

    // OnlyIf accepts an EnumDescriptor and determines whether this rule
    // is applicable.
    OnlyIf func(*desc.EnumDescriptor) bool
    // contains filtered or unexported fields
}

EnumRule defines a lint rule that is run on each enum.

func (*EnumRule) GetName Uses

func (r *EnumRule) GetName() RuleName

GetName returns the name of the rule.

func (*EnumRule) Lint Uses

func (r *EnumRule) Lint(fd *desc.FileDescriptor) []Problem

Lint visits every enum in the file and runs `LintEnum`.

If an `OnlyIf` function is provided on the rule, it is run against each enum, and if it returns false, the `LintEnum` function is not called.

type EnumValueRule Uses

type EnumValueRule struct {
    Name RuleName

    // LintEnumValue accepts a EnumValueDescriptor and lints it.
    LintEnumValue func(*desc.EnumValueDescriptor) []Problem

    // OnlyIf accepts an EnumValueDescriptor and determines whether this rule
    // is applicable.
    OnlyIf func(*desc.EnumValueDescriptor) bool
    // contains filtered or unexported fields
}

EnumValueRule defines a lint rule that is run on each enum value.

func (*EnumValueRule) GetName Uses

func (r *EnumValueRule) GetName() RuleName

GetName returns the name of the rule.

func (*EnumValueRule) Lint Uses

func (r *EnumValueRule) Lint(fd *desc.FileDescriptor) []Problem

Lint visits every enum value in the file and runs `LintEnum`.

If an `OnlyIf` function is provided on the rule, it is run against each enum value, and if it returns false, the `LintEnum` function is not called.

type FieldRule Uses

type FieldRule struct {
    Name RuleName

    // LintField accepts a FieldDescriptor and lints it, returning a slice of
    // Problems it finds.
    LintField func(*desc.FieldDescriptor) []Problem

    // OnlyIf accepts a FieldDescriptor and determines whether this rule
    // is applicable.
    OnlyIf func(*desc.FieldDescriptor) bool
    // contains filtered or unexported fields
}

FieldRule defines a lint rule that is run on each field within a file.

func (*FieldRule) GetName Uses

func (r *FieldRule) GetName() RuleName

GetName returns the name of the rule.

func (*FieldRule) Lint Uses

func (r *FieldRule) Lint(fd *desc.FileDescriptor) []Problem

Lint visits every field in the file and runs `LintField`.

If an `OnlyIf` function is provided on the rule, it is run against each field, and if it returns false, the `LintField` function is not called.

type FileRule Uses

type FileRule struct {
    Name RuleName

    // LintFile accepts a FileDescriptor and lints it, returning a slice of
    // Problems it finds.
    LintFile func(*desc.FileDescriptor) []Problem

    // OnlyIf accepts a FileDescriptor and determines whether this rule
    // is applicable.
    OnlyIf func(*desc.FileDescriptor) bool
    // contains filtered or unexported fields
}

FileRule defines a lint rule that checks a file as a whole.

func (*FileRule) GetName Uses

func (r *FileRule) GetName() RuleName

GetName returns the name of the rule.

func (*FileRule) Lint Uses

func (r *FileRule) Lint(fd *desc.FileDescriptor) []Problem

Lint forwards the FileDescriptor to the LintFile method defined on the FileRule.

type Linter Uses

type Linter struct {
    // contains filtered or unexported fields
}

Linter checks API files and returns a list of detected problems.

func New Uses

func New(rules RuleRegistry, configs Configs) *Linter

New creates and returns a linter with the given rules and configs.

func (*Linter) LintProtos Uses

func (l *Linter) LintProtos(files ...*desc.FileDescriptor) ([]Response, error)

LintProtos checks protobuf files and returns a list of problems or an error.

type MessageRule Uses

type MessageRule struct {
    Name RuleName

    // LintMessage accepts a MessageDescriptor and lints it, returning a slice
    // of Problems it finds.
    LintMessage func(*desc.MessageDescriptor) []Problem

    // OnlyIf accepts a MessageDescriptor and determines whether this rule
    // is applicable.
    OnlyIf func(*desc.MessageDescriptor) bool
    // contains filtered or unexported fields
}

MessageRule defines a lint rule that is run on each message in the file.

Both top-level messages and nested messages are visited.

func (*MessageRule) GetName Uses

func (r *MessageRule) GetName() RuleName

GetName returns the name of the rule.

func (*MessageRule) Lint Uses

func (r *MessageRule) Lint(fd *desc.FileDescriptor) []Problem

Lint visits every message in the file, and runs `LintMessage`.

If an `OnlyIf` function is provided on the rule, it is run against each message, and if it returns false, the `LintMessage` function is not called.

type MethodRule Uses

type MethodRule struct {
    Name RuleName

    // LintMethod accepts a MethodDescriptor and lints it.
    LintMethod func(*desc.MethodDescriptor) []Problem

    // OnlyIf accepts a MethodDescriptor and determines whether this rule
    // is applicable.
    OnlyIf func(*desc.MethodDescriptor) bool
    // contains filtered or unexported fields
}

MethodRule defines a lint rule that is run on each method.

func (*MethodRule) GetName Uses

func (r *MethodRule) GetName() RuleName

GetName returns the name of the rule.

func (*MethodRule) Lint Uses

func (r *MethodRule) Lint(fd *desc.FileDescriptor) []Problem

Lint visits every method in the file and runs `LintMethod`.

If an `OnlyIf` function is provided on the rule, it is run against each method, and if it returns false, the `LintMethod` function is not called.

type Problem Uses

type Problem struct {
    // Message provides a short description of the problem.
    // This should be no more than a single sentence.
    Message string

    // Suggestion provides a suggested fix, if applicable.
    //
    // This integrates with certain IDEs to provide "push-button" fixes,
    // so these need to be machine-readable, not just human-readable.
    // Additionally, when setting `Suggestion`, one should almost always set
    // `Location` also, to ensure that the text being replaced is sufficiently
    // precise.
    Suggestion string

    // Descriptor provides the descriptor related to the problem.
    //
    // If present and `Location` is not specified, then the starting location of
    // the descriptor is used as the location of the problem.
    Descriptor desc.Descriptor

    // Location provides the location of the problem.
    //
    // If unset, this defaults to the value of `Descriptor.GetSourceInfo()`.
    // This should almost always be set if `Suggestion` is set. The best way to
    // do this is by using the helper methods in `location.go`.
    Location *dpb.SourceCodeInfo_Location

    // RuleID provides the ID of the rule that this problem belongs to.
    // DO NOT SET: The linter sets this automatically.
    RuleID RuleName // FIXME: Make this private (cmd/summary_cli.go is the challenge).
    // contains filtered or unexported fields
}

Problem contains information about a result produced by an API Linter.

All rules return []Problem. Most lint rules return 0 or 1 problems, but occasionally there are rules that may return more than one.

func (Problem) MarshalJSON Uses

func (p Problem) MarshalJSON() ([]byte, error)

MarshalJSON defines how to represent a Problem in JSON.

func (Problem) MarshalYAML Uses

func (p Problem) MarshalYAML() (interface{}, error)

MarshalYAML defines how to represent a Problem in YAML.

type ProtoRule Uses

type ProtoRule interface {
    // GetName returns the name of the rule.
    GetName() RuleName

    // Lint accepts a FileDescriptor and lints it,
    // returning a slice of Problem objects it finds.
    Lint(*desc.FileDescriptor) []Problem
}

ProtoRule defines a lint rule that checks Google Protobuf APIs.

Anything that satisfies this interface can be used as a rule, but most rule authors will want to use the implementations provided.

Rules must only report errors in the file under which they are being run (not imported files).

type Response Uses

type Response struct {
    FilePath string    `json:"file_path" yaml:"file_path"`
    Problems []Problem `json:"problems" yaml:"problems"`
}

Response describes the result returned by a rule.

type RuleName Uses

type RuleName string

RuleName is an identifier for a rule. Allowed characters include a-z, 0-9, -.

The namespace separator :: is allowed between RuleName segments (for example, my-namespace::my-rule).

func NewRuleName Uses

func NewRuleName(aip int, name string) RuleName

NewRuleName creates a RuleName from an AIP number and a unique name within that AIP.

func (RuleName) HasPrefix Uses

func (r RuleName) HasPrefix(prefix ...string) bool

HasPrefix returns true if r contains prefix as a namespace. prefix parameters can be "::" delimited or specified as independent parameters. For example:

r := NewRuleName("foo", "bar", "baz") // string(r) == "foo::bar::baz"

r.HasPrefix("foo::bar") == true r.HasPrefix("foo", "bar") == true r.HasPrefix("foo", "bar", "baz") == true // matches the entire string r.HasPrefix("foo", "ba") == false // prefix must end on a delimiter

func (RuleName) IsValid Uses

func (r RuleName) IsValid() bool

IsValid checks if a RuleName is syntactically valid.

type RuleRegistry Uses

type RuleRegistry map[RuleName]ProtoRule

RuleRegistry is a registry for registering and looking up rules.

func NewRuleRegistry Uses

func NewRuleRegistry() RuleRegistry

NewRuleRegistry creates a new rule registry.

func (RuleRegistry) Register Uses

func (r RuleRegistry) Register(aip int, rules ...ProtoRule) error

Register registers the list of rules of the same AIP. Return an error if any of the rules is found duplicate in the registry.

type ServiceRule Uses

type ServiceRule struct {
    Name RuleName

    // LintService accepts a ServiceDescriptor and lints it.
    LintService func(*desc.ServiceDescriptor) []Problem

    // OnlyIf accepts a ServiceDescriptor and determines whether this rule
    // is applicable.
    OnlyIf func(*desc.ServiceDescriptor) bool
    // contains filtered or unexported fields
}

ServiceRule defines a lint rule that is run on each service.

func (*ServiceRule) GetName Uses

func (r *ServiceRule) GetName() RuleName

GetName returns the name of the rule.

func (*ServiceRule) Lint Uses

func (r *ServiceRule) Lint(fd *desc.FileDescriptor) []Problem

Lint visits every service in the file and runs `LintService`.

If an `OnlyIf` function is provided on the rule, it is run against each service, and if it returns false, the `LintService` function is not called.

Package lint imports 13 packages (graph) and is imported by 30 packages. Updated 2020-07-08. Refresh now. Tools for package owners.