lookout

README

lookout

A service for assisted code review, that allows running custom code Analyzers on pull requests.

SDK

If you are developing an Analyzer, please check SDK documentation.

It includes a curl-style binary that allows to trigger Analyzers directly, without launching a full lookout server.

Installation

go get github.com/src-d/lookout

Dependencies

The included ./docker-compose.yml allows to start all dependencies using Docker Compose

• bblfshd, on localhost:9432
• PostgreSQL, on localhost:5432 password postgres

Clone the repository, or download ./docker-compose.yml

Usage

To trigger the analysis on an actual pull request of a GitHub repository you will need GitHub access token.

With Docker

Run:

GITHUB_USER=<user> GITHUB_TOKEN=<token> REPO=github.com/<user>/<name> docker-compose up

Without Docker

1. Run dependencies manually or using docker-compose:

   docker-compose up bblfsh postgres
   

2. Initialize the database. This command will work for the PostgreSQL created by docker-compose, use -h to see other options.

   lookout migrate
   

3. Start an analyzer Any of the analyzers or a default dummy one, included in this repository

   go build -o analyzer ./cmd/dummy
   ./analyzer serve
   

4. Start a lookout server
   1. With posting analysis results on GitHub
      • Obtain GitHub access token
      • Run lookout serve --github-token <token> --github-user <user> <repository>
   2. Without posting analysis results (only printing)
      • lookout serve --dry-run <repository>

Configuration file

Global server configuration is stored in config.yml:

analyzers:
  - name: Example name # required, unique name of the analyzer
    addr: ipv4://localhost:10302 # required, gRPC address
    disabled: false # optional, false by default
    settings: # optional, this field is sent to analyzer "as is"
        threshold: 0.8

It's possible to override Analyzers configuration for a particular repository. To do that .lookout.yml must be present in the root of that repository.

Example:

analyzers:
  - name: Example name # must be the same as in server configuration, unknown names will be ignored
    disabled: true # local configuration can only disable analyzer, not enable
    settings: # settings for an analyzer will be merged with a global one
        threshold: 0.9
        mode: confident

Merging rules:

• Objects are deep merged
• Arrays are replaced
• Null value replaces object

Contribute

Contributions are more than welcome, if you are interested please take a look to our Contributing Guidelines.

Code of Conduct

All activities under source{d} projects are governed by the source{d} code of conduct.

License

Affero GPL v3.0, see LICENSE.

SDK package in ./sdk is released under the terms of the Apache License v2.0

Documentation

Overview

Package lookout provides gRPC APIs to implement analysis servers and clients.

Services

There are two services:

1. Analyzer: analyzers process source code changes and provide analysis results as text comments, possibly linked to specific parts of the code.

2. Data: provides simple access to source code changes.

Index

• Variables
• func RegisterAnalyzerServer(s *grpc.Server, srv AnalyzerServer)
• func RegisterDataServer(s *grpc.Server, srv *DataServerHandler)
• type AnalysisStatus
  • func (st AnalysisStatus) String() string
• type Analyzer
• type AnalyzerClient
  • func NewAnalyzerClient(conn *grpc.ClientConn) AnalyzerClient
• type AnalyzerComments
• type AnalyzerConfig
• type AnalyzerServer
• type Change
• type ChangeGetter
• type ChangeScanner
• type ChangesRequest
• type ClientChangeScanner
  • func (s *ClientChangeScanner) Change() *Change
  • func (s *ClientChangeScanner) Close() error
  • func (s *ClientChangeScanner) Err() error
  • func (s *ClientChangeScanner) Next() bool
• type ClientFileScanner
  • func (s *ClientFileScanner) Close() error
  • func (s *ClientFileScanner) Err() error
  • func (s *ClientFileScanner) File() *File
  • func (s *ClientFileScanner) Next() bool
• type Comment
• type CommitRevision
• type DataClient
  • func NewDataClient(cc *grpc.ClientConn) *DataClient
  • func (c *DataClient) GetChanges(ctx context.Context, in *ChangesRequest, opts ...grpc.CallOption) (ChangeScanner, error)
  • func (c *DataClient) GetFiles(ctx context.Context, in *FilesRequest, opts ...grpc.CallOption) (FileScanner, error)
• type DataServerHandler
  • func (s *DataServerHandler) GetChanges(req *ChangesRequest, srv pb.Data_GetChangesServer) (err error)
  • func (s *DataServerHandler) GetFiles(req *FilesRequest, srv pb.Data_GetFilesServer) (err error)
• type Event
• type EventHandler
• type EventID
• type EventResponse
• type EventType
• type File
• type FileGetter
• type FileScanner
• type FilesRequest
• type FnChangeScanner
  • func (s *FnChangeScanner) Change() *Change
  • func (s *FnChangeScanner) Close() error
  • func (s *FnChangeScanner) Err() error
  • func (s *FnChangeScanner) Next() bool
• type FnFileScanner
  • func (s *FnFileScanner) Close() error
  • func (s *FnFileScanner) Err() error
  • func (s *FnFileScanner) File() *File
  • func (s *FnFileScanner) Next() bool
• type Poster
• type PushEvent
• type ReferencePointer
• type RepositoryInfo
• type ReviewEvent
• type WatchOptions
• type Watcher

Variables

var (
	// NoErrStopWatcher if a new error of this kind is returned by EventHandler
	// the Watcher.Watch function exits without error.
	NoErrStopWatcher = errors.NewKind("Stop watcher")
)

Functions

func RegisterAnalyzerServer

func RegisterAnalyzerServer(s *grpc.Server, srv AnalyzerServer)

func RegisterDataServer

func RegisterDataServer(s *grpc.Server, srv *DataServerHandler)

Types

type AnalysisStatus

type AnalysisStatus int

AnalysisStatus is the status reported to the provider to inform that we are performing an analysis, or that it has finished

const (

	// ErrorAnalysisStatus represents an error status
	ErrorAnalysisStatus AnalysisStatus
	// FailureAnalysisStatus represents a failure status
	FailureAnalysisStatus
	// PendingAnalysisStatus represents a pending status
	PendingAnalysisStatus
	// SuccessAnalysisStatus represents a success status
	SuccessAnalysisStatus
)

func (AnalysisStatus) String

func (st AnalysisStatus) String() string

type Analyzer

type Analyzer struct {
	Client AnalyzerClient
	Config AnalyzerConfig
}

Analyzer is a struct of analyzer client and config

type AnalyzerClient

type AnalyzerClient = pb.AnalyzerClient

func NewAnalyzerClient

func NewAnalyzerClient(conn *grpc.ClientConn) AnalyzerClient

type AnalyzerComments

type AnalyzerComments struct {
	Config   AnalyzerConfig
	Comments []*Comment
}

AnalyzerComments contains a group of comments and the config for the analyzer that created them

type AnalyzerConfig

type AnalyzerConfig struct {
	Name string
	// Addr is gRPC URL.
	// can be defined only in global config, repository-scoped configuration is ignored
	Addr string
	// Disabled repository-scoped configuration can accept only true value, false value is ignored
	Disabled bool
	// Feedback is a url to be linked after each comment
	Feedback string
	// Settings any configuration for an analyzer
	Settings map[string]interface{}
}

AnalyzerConfig is a configuration of analyzer

type AnalyzerServer

type AnalyzerServer = pb.AnalyzerServer

type Change

type Change = pb.Change

type ChangeGetter

type ChangeGetter interface {
	// GetChanges returns a ChangeScanner that scans all changes according
	// to the request.
	GetChanges(context.Context, *ChangesRequest) (ChangeScanner, error)
}

ChangeGetter is used to retrieve code changes.

type ChangeScanner

type ChangeScanner interface {
	// Next advances the scanner to the next change. It returns true if a new
	// change is found, and false otherwise. After the user is done scanning,
	// Err must be called to check if all changes were consumed or there was an
	// error.
	Next() bool
	// Err returns any error found during scanning.
	Err() error
	// Change returns the current change.
	Change() *Change
	// Close closes the scanner.
	Close() error
}

ChangeScanner is a scanner for changes.

type ChangesRequest

type ChangesRequest = pb.ChangesRequest

type ClientChangeScanner

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

func (*ClientChangeScanner) Change

func (s *ClientChangeScanner) Change() *Change

func (*ClientChangeScanner) Close

func (s *ClientChangeScanner) Close() error

func (*ClientChangeScanner) Err

func (s *ClientChangeScanner) Err() error

func (*ClientChangeScanner) Next

func (s *ClientChangeScanner) Next() bool

type ClientFileScanner

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

func (*ClientFileScanner) Close

func (s *ClientFileScanner) Close() error

func (*ClientFileScanner) Err

func (s *ClientFileScanner) Err() error

func (*ClientFileScanner) File

func (s *ClientFileScanner) File() *File

func (*ClientFileScanner) Next

func (s *ClientFileScanner) Next() bool

type Comment

type Comment = pb.Comment

type CommitRevision

type CommitRevision = pb.CommitRevision

type DataClient

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

func NewDataClient

func NewDataClient(cc *grpc.ClientConn) *DataClient

func (*DataClient) GetChanges

func (c *DataClient) GetChanges(ctx context.Context, in *ChangesRequest, opts ...grpc.CallOption) (
	ChangeScanner, error)

func (*DataClient) GetFiles

func (c *DataClient) GetFiles(ctx context.Context, in *FilesRequest, opts ...grpc.CallOption) (
	FileScanner, error)

type DataServerHandler

type DataServerHandler struct {
	ChangeGetter ChangeGetter
	FileGetter   FileGetter
}

func (*DataServerHandler) GetChanges

func (s *DataServerHandler) GetChanges(req *ChangesRequest,
	srv pb.Data_GetChangesServer) (err error)

func (*DataServerHandler) GetFiles

func (s *DataServerHandler) GetFiles(req *FilesRequest, srv pb.Data_GetFilesServer) (err error)

type Event

type Event interface {
	// ID returns the EventID.
	ID() EventID
	// Type returns the EventType, in order to identify the concreate type of
	// the event.
	Type() EventType
	// Revision returns a commit revision, containing the head and the base of
	// the changes.
	Revision() *CommitRevision
	// Validate returns an error if the event is malformed
	Validate() error
}

Event represents a repository event.

type EventHandler

type EventHandler func(Event) error

EventHandler funciton to be called when a new event happends.

type EventID

type EventID = pb.EventID

type EventResponse

type EventResponse = pb.EventResponse

type EventType

type EventType = pb.EventType

type File

type File = pb.File

type FileGetter

type FileGetter interface {
	// GetFiles returns a FilesScanner that scans all files according
	// to the request.
	GetFiles(context.Context, *FilesRequest) (FileScanner, error)
}

FileGetter is used to retrieve all code for a revision.

type FileScanner

type FileScanner interface {
	// Next advances the scanner to the next file. It returns true if a new
	// file is found, and false otherwise. After the user is done scanning,
	// Err must be called to check if all files were consumed or there was an
	// error.
	Next() bool
	// Err returns any error found during scanning.
	Err() error
	// File returns the current file.
	File() *File
	// Close closes the scanner.
	Close() error
}

FileScanner is a scanner for files.

type FilesRequest

type FilesRequest = pb.FilesRequest

type FnChangeScanner

type FnChangeScanner struct {
	Scanner ChangeScanner
	Fn      func(*Change) (bool, error)
	OnStart func() error
	// contains filtered or unexported fields
}

FnChangeScanner implements ChangeScanner using functions

func (*FnChangeScanner) Change

func (s *FnChangeScanner) Change() *Change

func (*FnChangeScanner) Close

func (s *FnChangeScanner) Close() error

func (*FnChangeScanner) Err

func (s *FnChangeScanner) Err() error

func (*FnChangeScanner) Next

func (s *FnChangeScanner) Next() bool

type FnFileScanner

type FnFileScanner struct {
	Scanner FileScanner
	Fn      func(*File) (bool, error)
	OnStart func() error
	// contains filtered or unexported fields
}

FnFileScanner implements FileScanner using functions

func (*FnFileScanner) Close

func (s *FnFileScanner) Close() error

func (*FnFileScanner) Err

func (s *FnFileScanner) Err() error

func (*FnFileScanner) File

func (s *FnFileScanner) File() *File

func (*FnFileScanner) Next

func (s *FnFileScanner) Next() bool

type Poster

type Poster interface {
	// Post posts comments about an event.
	Post(context.Context, Event, []AnalyzerComments) error

	// Status sends the current analysis status to the provider
	Status(context.Context, Event, AnalysisStatus) error
}

Poster can post comments about an event.

type PushEvent

type PushEvent = pb.PushEvent

type ReferencePointer

type ReferencePointer = pb.ReferencePointer

type RepositoryInfo

type RepositoryInfo = pb.RepositoryInfo

type ReviewEvent

type ReviewEvent = pb.ReviewEvent

type WatchOptions

type WatchOptions struct {
	URLs []string
}

WatchOptions options to use in the Watcher constructors.

type Watcher

type Watcher interface {
	// Watch for new events triggering the EventHandler for each new issue,
	// it stops until an error is returned by the EventHandler. Network errors
	// or other temporal errors are handled as non-fatal errors, just logging it.
	Watch(context.Context, EventHandler) error
}

Watcher watch for new events in given provider.