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 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 no 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
• build - checks if k6 can be built with the extension
• smoke - checks if the smoke test script exists and runs successfully (smoke.js, smoke.ts, smoke.test.js or smoke.test.ts in the test,tests, examples, scripts or in the base directory)
• codeowners - checks if there is a CODEOWNERS file (for official extensions) (in the .github or docs or in the base directory)
• types - checks if the TypeScript API declaration file exists (index.d.ts in the docs, api-docs or the base directory)

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
✔ license             
  found `LICENSE` as `Apache-2.0` license
✔ git                 
  found git worktree
✔ versions            
  found `13` versions, the latest is `v1.0.0`
✔ build               
  can be built with the latest k6 version
✔ smoke               
  `smoke.test.ts` successfully run with k6
✔ examples            
  found `examples` as examples directory
✔ types               
  found `index.d.ts` file

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 `LICENSE` as `Apache-2.0` license",
      "id": "license",
      "passed": true
    },
    {
      "details": "found git worktree",
      "id": "git",
      "passed": true
    },
    {
      "details": "found `13` versions, the latest is `v1.0.0`",
      "id": "versions",
      "passed": true
    },
    {
      "details": "can be built with the latest k6 version",
      "id": "build",
      "passed": true
    },
    {
      "details": "`smoke.test.ts` successfully run with k6",
      "id": "smoke",
      "passed": true
    },
    {
      "details": "found `examples` as examples directory",
      "id": "examples",
      "passed": true
    },
    {
      "details": "found `index.d.ts` file",
      "id": "types",
      "passed": true
    }
  ],
  "grade": "A",
  "level": 100,
  "timestamp": 1731604019
}

CLI

k6lint

Linter for k6 extensions

Synopsis

Static analyzer for k6 extensions

k6lint analyzes the source of the k6 extension and try to build k6 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)
      --official              enable extra checks for official extensions
  -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 CheckerBuild Checker = "build"

const CheckerCodeowners Checker = "codeowners"

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 CheckerSmoke Checker = "smoke"

const CheckerTypes Checker = "types"

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

	// Official can be set true to enable extra checkers (like codeowners) for official extensions.
	Official bool
}

Options contains settings that modify the linter's operation.