difflint

README

difflint

🔍 Git-based linter tool that scans code changes for compliance with defined rules in source code.

Installation

go get -u github.com/EthanThatOneKid/difflint

Usage

difflint --help

Single file

# File: ./main.py

#LINT.IF

print("Edit me first!")

#LINT.END bar

#LINT.IF :bar

print("Edit me second!")

#LINT.END

Multiple files

# File ./foo.py

#LINT.IF

print("Edit me first!")

#LINT.END bar

# File: ./main.py

#LINT.IF ./foo.py:bar

print("Edit me second!")

#LINT.END

Exhaustive switch statement

In programming languages lacking a comprehensive match statement for enumerations, our only option is to verify whether the switch statement aligns with the enumerated type.

//LINT.IF

enum Thing {
  ONE = 1,
  TWO = 2,
}

//LINT.END :thing_enum

//LINT.IF :thing_enum

switch (thing) {
  case Thing.ONE: {
    return doThingOne();
  }

  case Thing.TWO: {
    return doThingTwo();
  }
}

//LINT.END

Custom file extensions

git diff | difflint --ext_map="difflint.json"

difflint.json

{
  "yaml": ["#LINT.?"]
}

Development

Run the tool from source with the Go toolchain:

go run cli/main.go --help

---

Created with 💖 by @EthanThatOneKid

Documentation

Index

• Variables
• func Include(pathname string, include, exclude []string) (bool, error)
• func Intersects(a, b Range) bool
• func RulesMapFromHunks(hunks []Hunk, options LintOptions) (map[string][]Rule, map[string]struct{}, error)
• func TargetKey(pathname string, target Target) string
• func Walk(root string, include []string, exclude []string, callback filepath.WalkFunc) error
• type ExtFileJSON
• type ExtMap
  • func NewExtMap(path string) *ExtMap
  • func (o *ExtMap) With(ext, tpl string) *ExtMap
• type Hunk
  • func ParseHunks(r io.Reader, include, exclude []string) ([]Hunk, error)
• type LintOptions
  • func (o *LintOptions) TemplatesFromFile(file string) ([]string, error)
• type LintResult
  • func Lint(o LintOptions) (*LintResult, error)
• type Range
• type Rule
• type Target
• type UnsatisfiedRule
• type UnsatisfiedRules
  • func Check(rulesMap map[string][]Rule, targetsMap map[string]struct{}) (UnsatisfiedRules, error)
  • func Do(r io.Reader, include, exclude []string, extMapPath string) (UnsatisfiedRules, error)
  • func (r *UnsatisfiedRules) String() string

Variables

var (
	// DefaultTemplates is the default list of directive templates.
	DefaultTemplates = []string{
		"#LINT.?",
		"//LINT.?",
		"/*LINT.?",
		"<!--LINT.?",
		"'LINT.?",
	}

	// DefaultFileExtMap is the default map of file extensions to directive templates.
	DefaultFileExtMap = map[string][]int{
		"py":       {0},
		"sh":       {0},
		"go":       {1},
		"js":       {1, 2},
		"jsx":      {1, 2},
		"mjs":      {1, 2},
		"ts":       {1, 2},
		"tsx":      {1, 2},
		"jsonc":    {1, 2},
		"c":        {1, 2},
		"cc":       {1, 2},
		"cpp":      {1, 2},
		"h":        {1, 2},
		"hpp":      {1, 2},
		"java":     {1},
		"rs":       {1},
		"swift":    {1},
		"svelte":   {1, 2, 3},
		"css":      {2},
		"html":     {3},
		"md":       {3},
		"markdown": {3},
		"bas":      {4},
	}
)

Functions

func Include

func Include(pathname string, include, exclude []string) (bool, error)

Include determines if a given diff should be included in the linting process.

func Intersects

func Intersects(a, b Range) bool

Intersects returns true if the given ranges intersect.

func RulesMapFromHunks

func RulesMapFromHunks(hunks []Hunk, options LintOptions) (map[string][]Rule, map[string]struct{}, error)

RulesMapFromHunks parses rules from the given hunks by file name and returns the map of rules and the set of all the target keys that are present.

func TargetKey

func TargetKey(pathname string, target Target) string

TargetKey returns the key for the given target.

func Walk

func Walk(root string, include []string, exclude []string, callback filepath.WalkFunc) error

Walk walks the file tree rooted at root, calling callback for each file or directory in the tree, including root.

Types

type ExtFileJSON

type ExtFileJSON map[string][]string

ExtFileJSON is a JSON representation of a file extension to directive template map.

type ExtMap

type ExtMap struct {
	// Templates is the list of directive templates.
	Templates []string

	// FileExtMap is a map of file extensions to directive templates.
	FileExtMap map[string][]int
}

ExtMap represents the extensions and templates for a linting operation.

func NewExtMap

func NewExtMap(path string) *ExtMap

NewExtMap returns a new ExtMap instance.

func (*ExtMap) With

func (o *ExtMap) With(ext, tpl string) *ExtMap

With adds a directive template for a file extension.

type Hunk

type Hunk struct {
	// File specifier of the defined range.
	File string

	// Range of code in which a diff hunk intersects.
	Range Range
}

Hunk represents a diff hunk that must be present in the diff.

func ParseHunks

func ParseHunks(r io.Reader, include, exclude []string) ([]Hunk, error)

ParseHunks parses the input diff and returns the extracted file paths along with associated line number ranges.

type LintOptions

type LintOptions struct {
	// Reader is the reader from which the diff is read.
	Reader io.Reader

	// Include is a list of file patterns to include in the linting.
	Include []string

	// Exclude is a list of file patterns to exclude from the linting.
	Exclude []string

	// Templates is the list of directive templates.
	Templates []string // []string{"//LINT.?", "#LINT.?", "<!-- LINT.? -->"}

	// FileExtMap is a map of file extensions to directive templates.
	FileExtMap map[string][]int // map[string][]int{".go": []int{0}, ".py": []int{1}}

	// DefaultTemplate is the default directive template.
	DefaultTemplate int
}

LintOptions represents the options for a linting operation.

func (*LintOptions) TemplatesFromFile

func (o *LintOptions) TemplatesFromFile(file string) ([]string, error)

TemplatesFromFile returns the directive templates for the given file type.

type LintResult

type LintResult struct {
	// List of rules that were not satisfied.
	UnsatisfiedRules UnsatisfiedRules
}

Result of a linting operation.

func Lint

func Lint(o LintOptions) (*LintResult, error)

Lint lints the given hunks against the given rules and returns the result.

type Range

type Range struct {
	// Start line number.
	Start int

	// End line number.
	End int
}

Range represents a range of line numbers.

type Rule

type Rule struct {
	// Hunk is the diff hunk that must be present in the diff.
	Hunk Hunk

	// Targets are the files or ranges of code that must be present in the diff if the hunk is present.
	Targets []Target

	// Present is true if the change is present in the diff from which the rules were parsed.
	Present bool

	// ID is an optional, unique identifier for the rule.
	ID *string
}

A rule says that file or range of code must be present in the diff if another range is present.

type Target

type Target struct {
	// File specifier expected to contain a diff hunk.
	File *string

	// ID is the ID of the range of code in which a diff hunk intersects.
	ID *string
}

Target represents a file or range of code that must be present in the diff if a diff hunk is present.

type UnsatisfiedRule

type UnsatisfiedRule struct {
	// Rule that is not satisfied.
	Rule

	// UnsatisfiedTargets is the list of target indices that are not satisfied.
	UnsatisfiedTargets map[int]struct{}
}

UnsatisfiedRule represents a rule that is not satisfied.

type UnsatisfiedRules

type UnsatisfiedRules []UnsatisfiedRule

UnsatisfiedRules is a list of unsatisfied rules.

func Check

func Check(rulesMap map[string][]Rule, targetsMap map[string]struct{}) (UnsatisfiedRules, error)

Check returns the list of unsatisfied rules for the given map of rules.

func Do

func Do(r io.Reader, include, exclude []string, extMapPath string) (UnsatisfiedRules, error)

Do is the difflint command's entrypoint.

func (*UnsatisfiedRules) String

func (r *UnsatisfiedRules) String() string

String returns a string representation of the unsatisfied rules.