linter

README

jsonnet-lint

This is a linter for Jsonnet. It is alpha stage, but it should be already useful.

Features

The linter detect the following kinds of issues:

• "Type" problems, such as:
  • Accessing nonexistent fields
  • Calling a function with a wrong number of arguments or named arguments which do not match the parameters
  • Trying to call a value which is not a function
  • Trying to index a value which is not an object, array or a string
• Unused variables
• Endlessly looping constructs, which are always invalid, but often appear as a result of confusion about language semantics (e.g. local x = x + 1)
• Anything that is statically detected during normal execution, such as syntax errors and undeclared variables.

Usage

jsonnet-lint [options] <filename>

Design

Goals

The purpose of the linter is to aid development by providing quick and clear feedback about simple problems. With that in mind I defined the following goals:

• It should find common problems, especially the kinds resulting from typos, trivial omissions and issues resulting from misunderstanding of the semantics.
• It should find problems in the parts of code which are not reached by the tests (especially important due to the lazy evaluation).
• It must be practical to use with the existing Jsonnet code, without any need for modification.
• It must be fast enough so it is practical to always run the linter before execution during development. The overhead required to run the linter prior to running the program in real world conditions should be comparable with parsing and desugaring.
• It must be conservative regarding the reported problems. False negatives are preferable to false positives. False positives are allowed as long as they relate to code which is going to be confusing for humans to read or if they can be worked around easily while preserving readability.
• Its results must be stable, i.e. trivial changes such as changing the order of variables in local expressions should not change the result nontrivially.
• It must preserve the abstractions. Validity of the definitions should not depend on their use. In particular calling functions with specific arguments or accessing fields of objects should not cause errors in their definitions.
• It should be possible to explicitly silence individual errors, so that occasional acknowledged false positives do not distract the users. This is espcially important if a clean pass is enforced in Continuous Integration.

Rules

The above goals naturally lead to the some more specific code-level rules which all analyses must obey:

• All expressions should be checked, even the provably dead code.
• Always consider both branches of the if expression possible (even if the condition is trivially always true or always false).
• Correctness of a function definition should not depend on how it is used. In particular when analyzing the definition assume that function arguments can take arbitrary values.
• Correctness of an object definition should not depend on how it is used. In particular when analyzing the definition assume that the object may be part of an arbitrary inheritance chain

Documentation

Overview

Package linter analyses Jsonnet code for code "smells".

Index

• func LintSnippet(vm *jsonnet.VM, output io.Writer, snippets []Snippet) bool
• type ErrorWriter
• type Snippet

Functions

func LintSnippet

func LintSnippet(vm *jsonnet.VM, output io.Writer, snippets []Snippet) bool

LintSnippet checks for problems in code snippet(s).

Types

type ErrorWriter

type ErrorWriter struct {
	ErrorsFound bool
	Writer      io.Writer
}

ErrorWriter encapsulates a writer and an error state indicating when at least one error has been written to the writer.

type Snippet

type Snippet struct {
	FileName string
	Code     string
}

Snippet represents a jsonnet file data that to be linted