gqlanalysis

README

gqlanalysis

gqlanalysis defines the interface between a modular static analysis for GraphQL in Go. gqlanalysis is inspired by go/analysis.

gqlanalysis makes easy to develop static analysis tools for GraphQL in Go.

How to use

Analyzer

The primary type in the API is Analyzer. An Analyzer statically describes an analysis function: its name, documentation, flags, relationship to other analyzers, and of course, its logic.

package lackid

var Analyzer = &gqlanalysis.Analyzer{
	Name: "lackid",
	Doc:  "lackid finds a selection for a type which has id field but the selection does not have id",
	Run:  run,
	...
}

func run(pass *gqlanalysis.Pass) (interface{}, error) {
	...
}

Driver

An analysis driver is a program that runs a set of analyses and prints the diagnostics that they report. The driver program must import the list of Analyzers it needs.

A typical driver can be created with multichecker package.

package main

import (
        "github.com/gqlgo/gqlanalysis/multichecker"
        "github.com/gqlgo/lackid"
        "github.com/gqlgo/myanalyzer"
)

func main() {
        multichecker.Main(
		lackid.Analyzer,
		myanalyzer.Analyzer,
	)
}

Pass

A Pass describes a single unit of work: the application of a particular Analyzer to given GraphQL's schema and query files. The Pass provides information to the Analyzer's Run function about schemas and queries being analyzed, and provides operations to the Run function for reporting diagnostics and other information back to the driver.

type Pass struct {
        Analyzer *Analyzer

        Schema   *ast.Schema
        Queries  []*ast.QueryDocument
        Comments []*Comment

        Report   func(*Diagnostic)
        ResultOf map[*Analyzer]interface{}
}

Diagnostic

A Diagnostic is a message associated with a source location. Pass can report a diagnostic via Report field or Reportf method.

type Diagnostic struct {
        Pos     *ast.Position
        Message string
}

Implementations of Analyzer

• gqlgo/lackid - Detect lack of id in GraphQL query

Author

Documentation

Index

• func Version() string
• type Analyzer
  • func (a *Analyzer) String() string
• type Comment
  • func ReadComments(src *ast.Source) ([]*Comment, error)
  • func (c *Comment) String() string
• type Diagnostic
• type Pass
  • func (pass *Pass) Reportf(pos *ast.Position, format string, args ...interface{})

Functions

func Version

func Version() string

Version returns version of gqlanalysis.

Types

type Analyzer

type Analyzer struct {
	Name       string
	Run        func(pass *Pass) (interface{}, error)
	Doc        string
	Flags      flag.FlagSet
	Requires   []*Analyzer
	ResultType reflect.Type
}

Analyzer is an analyzer for .graphql file. It is inspired by golang.org/x/tools/go/analysis.Analyzer.

func (*Analyzer) String

func (a *Analyzer) String() string

type Comment

type Comment struct {
	Value string
	Pos   ast.Position
}

Comment represents a comment line of a graphql file.

func ReadComments

func ReadComments(src *ast.Source) ([]*Comment, error)

ReadComments reads comments from src. Ofcourse, src is io.Reader better than *ast.Source but it use *ast.Soruce for compatibility with gqlparser. Unfortunately, gqlparser does not toknize comments. See: https://github.com/vektah/gqlparser/issues/145

func (*Comment) String

func (c *Comment) String() string

String implements fmt.Stringer.

type Diagnostic

type Diagnostic struct {
	Pos     *ast.Position
	Message string
}

A Diagnostic is a message associated with a source location.

type Pass

type Pass struct {
	Analyzer *Analyzer

	Schema   *ast.Schema
	Queries  []*ast.QueryDocument
	Comments []*Comment

	Report   func(*Diagnostic)
	ResultOf map[*Analyzer]interface{}
}

A Pass provides information to the Run function that applies a specific analyzer. The Run function should not call any of the Pass functions concurrently.

func (*Pass) Reportf

func (pass *Pass) Reportf(pos *ast.Position, format string, args ...interface{})

Reportf reports a diagnostic with a format.