lookout-sdk

lookout SDK

What is lookout SDK?

Lookout SDK is a toolkit for writing new analyzers for the lookout.

What does it provide

It provides to an analyzer an easy access to the DataService API though a gRPC service.

DataService abstracts all data access and details of dealing with actual Git repositories, UAST extraction, programming language detection, etc. This way the analyzer can focus focus only on source code analysis logic.

The architecture of lookout and its components are described in src-d/lookout/docs

SDK includes:

• proto definitions
• pre-generated libraries code for Golang and Python
• quickstart documentation on how to write an analyzer

How to create a new Analyzer

Essentially, every analyzer is a gRCP server that implements Analyzer service. Lookout itself acts as a gRCP client and will push your analyzer whenever a new Pull Request is ready for analysis.

Golang

Steps:

• use pre-generated code for gRPC from gopkg.in/src-d/lookout-sdk.v0/pb
• implement Analyzer service interface. Example:

  NotifyReviewEvent(ctx context.Context, review *pb.ReviewEvent) (*pb.EventResponse, error)
  NotifyPushEvent(context.Context, *pb.PushEvent) (*pb.EventResponse, error)
  

  • analyzer should request a stream of files and UASTs from DataService that lookout exposes, by default, on localhost:10301
  • analyzer has options to ask either for all files, or just thee changed ones, as well as UASTs, language, full file content and/or exclude some paths: by regexp, or just all vendored paths
  • analyzer has to return a list of Comment messages
• run gRPC server to listen for requests from the lookout

SDK contains a quickstart example of an Analyzer that detects language and number of functions for every file language-analyzer.go:

• go get -u .
• go run language-analyzer.go

Python

• pip install lookout-sdk
• using pre-generated code from (TK python import)
• implement Analyzer class that extends AnalyzerServicer. Example:

  def NotifyReviewEvent(self, request, context):
  def NotifyPushEvent(self, request, context):
  

• start grpc server and add Analyzer instance to it

SDK conatains a quickstart example of an Analyzer that detects language and number of functions for every file language-analyzer.py:

• pip3 install -r analyzer-requirements.txt
• python3 language-analyzer.py

How to test analyzer

• get lookout-sdk binary from src-d/lookout releases
• run bblfshd
• build and start analyzer e.g. Golang
  • go get -u .
  • go run language-analyzer.go , or Python
  • pip3 install -r analyzer-requirements.txt
  • python3 language-analyzer.py
• test without Github access, on the latest commit in some Git repository in local FS

/lookout review \
  --log-level=debug \
  --git-dir="$GOPATH/src/gopkg.in/src-d/lookout-sdk.v0" \
  "ipv4://localhost:2020"

this will create a "mock" Review event and notify the analyzer, as if you were creating a PR from HEAD~1.

(TK link to lookout-sdk binary desctiption + it's options)

Caveats

• client: disable secure connection on dialing with grpc.WithInsecure()
• client: turn off gRCP [fail-fast](TK link)
• client/server: set max gRCP message size

How to update SDK

• re-generate all the code using (TK link to .sh), commit
• tag a realease

License

Apache License v2.0