k6lint

README

k6lint

Linter for k6 extensions

k6lint is a command line tool and a library for static analysis of the source of k6 extensions. The analysis is done without building a k6 executable with the extension.

The contents of the source directory are used for analysis. If the directory is a git workdir, it also analyzes the git metadata. The analysis is completely local and does not use external APIs (e.g. repository manager API) or services.

The result of the analysis is compliance expressed as a percentage (0-100). This value is created as a weighted, normalized value of the scores of each checker. A compliance grade is created from the percentage value (A-F).

The detailed result of the checks are described in a JSON schema.

Checkers

• module - checks if there is a valid go.mod
• replace - checks if there is a replace directive in go.mod
• readme - checks if there is a readme file
• examples - checks if there are files in the examples directory
• license - checks whether there is a suitable OSS license
• git - checks if the directory is git workdir
• versions - checks for semantic versioning git tags

Install

Precompiled binaries can be downloaded and installed from the Releases page.

If you have a go development environment, the installation can also be done with the following command:

go install github.com/grafana/k6lint/cmd/k6lint@latest

Use

k6lint source-directory

output

k6 extension compliance
──────────┬─────────────
 grade  A │ level  100% 

Details
───────
✔ module              
  found `github.com/grafana/xk6-sql` as go module
✔ replace             
  no `replace` directive in the `go.mod` file
✔ readme              
  found `README.md` as README file
✔ examples            
  found `examples` as examples directory
✔ license             
  found `LICENSE` as `Apache-2.0` license
✔ git                 
  found git worktree
✔ versions            
  found `6` versions, the latest is `v0.3.0`

JSON output

{
  "checks": [
    {
      "details": "found `github.com/grafana/xk6-sql` as go module",
      "id": "module",
      "passed": true
    },
    {
      "details": "no `replace` directive in the `go.mod` file",
      "id": "replace",
      "passed": true
    },
    {
      "details": "found `README.md` as README file",
      "id": "readme",
      "passed": true
    },
    {
      "details": "found `examples` as examples directory",
      "id": "examples",
      "passed": true
    },
    {
      "details": "found `LICENSE` as `Apache-2.0` license",
      "id": "license",
      "passed": true
    },
    {
      "details": "found git worktree",
      "id": "git",
      "passed": true
    },
    {
      "details": "found `6` versions, the latest is `v0.3.0`",
      "id": "versions",
      "passed": true
    }
  ],
  "grade": "A",
  "level": 100,
  "timestamp": 1724833956
}

CLI

k6lint

Linter for k6 extensions

Synopsis

Static analyzer for k6 extensions

k6lint analyzes the source of the k6 extension without building a k6 executable with the extension.

By default, text output is generated. The --json flag can be used to generate the result in JSON format.

If the grade is C or higher, the command is successful, otherwise it returns an exit code larger than 0. This passing grade can be modified using the --passing flag.

k6lint [flags] [directory]

Flags

      --passing A|B|C|D|E|F   set lowest passing grade (default C)
  -q, --quiet                 no output, only validation
  -o, --out string            write output to file instead of stdout
      --json                  generate JSON output
  -c, --compact               compact instead of pretty-printed JSON output
  -V, --version               print version
  -h, --help                  help for k6lint

Documentation

Overview

Package k6lint contains the public API of the k6 extension linter.

Index

• type Check
• type Checker
  • func ParseChecker(val string) (Checker, error)
• type Compliance
  • func Lint(ctx context.Context, dir string, opts *Options) (*Compliance, error)
• type Grade
  • func (g *Grade) Set(val string) error
  • func (g *Grade) String() string
  • func (g *Grade) Type() string
• type Options

Types

type Check

type Check struct {
	// Textual explanation of the check result.
	//
	Details string `json:"details,omitempty" yaml:"details,omitempty" mapstructure:"details,omitempty"`

	// The ID of the checker.
	//
	// It identifies the method of check, not the execution of the check.
	//
	ID Checker `json:"id" yaml:"id" mapstructure:"id"`

	// The result of the check.
	//
	// A true value of the passed property indicates a successful check, while a false
	// value indicates a failure.
	//
	Passed bool `json:"passed" yaml:"passed" mapstructure:"passed"`
}

The result of a particular inspection.

type Checker

type Checker string

const CheckerExamples Checker = "examples"

const CheckerGit Checker = "git"

const CheckerLicense Checker = "license"

const CheckerModule Checker = "module"

const CheckerReadme Checker = "readme"

const CheckerReplace Checker = "replace"

const CheckerVersions Checker = "versions"

func ParseChecker

func ParseChecker(val string) (Checker, error)

ParseChecker parses checker name from string.

type Compliance

type Compliance struct {
	// Results of individual checks.
	//
	Checks []Check `json:"checks,omitempty" yaml:"checks,omitempty" mapstructure:"checks,omitempty"`

	// The results of the checks are in the form of a grade.
	//
	Grade Grade `json:"grade" yaml:"grade" mapstructure:"grade"`

	// Compliance expressed as a percentage.
	//
	Level int `json:"level" yaml:"level" mapstructure:"level"`

	// Compliance check timestamp.
	//
	// The timestamp property contains the start timestamp of the check in Unix time
	// format (the number of non-leap seconds that have elapsed since 00:00:00 UTC on
	// 1st January 1970).
	//
	Timestamp float64 `json:"timestamp" yaml:"timestamp" mapstructure:"timestamp"`
}

The result of the extension's k6 compliance checks.

func Lint

func Lint(ctx context.Context, dir string, opts *Options) (*Compliance, error)

Lint checks the directory specified in the dir parameter as the k6 extension source directory.

type Grade

type Grade string

const GradeA Grade = "A"

const GradeB Grade = "B"

const GradeC Grade = "C"

const GradeD Grade = "D"

const GradeE Grade = "E"

const GradeF Grade = "F"

const GradeG Grade = "G"

func (*Grade) Set

func (g *Grade) Set(val string) error

Set implements cobra.Value#Set().

func (*Grade) String

func (g *Grade) String() string

func (*Grade) Type

func (g *Grade) Type() string

Type implements cobra.Value#Type().

type Options

type Options struct {
	// Passed contains a list of checkers that have already been marked as successful.
	Passed []Checker
}

Options contains settings that modify the linter's operation.