api

Documentation

Index

• func Slug(name string) string
• type CQLinter
• type CQLinterResult
• type CQLinterType
• type Category
  • func (c Category) String() string
• type Configurable
• type ConfigurableLinter
• type DependencyManager
• type DependencyManagerList
  • func (list DependencyManagerList) Contains(target DependencyManager) bool
  • func (list DependencyManagerList) ContainsAllTypes(targets ...DependencyManagerType) bool
  • func (list DependencyManagerList) ContainsType(target DependencyManagerType) bool
  • func (list DependencyManagerList) Main() DependencyManager
• type DependencyManagerType
• type GitInfo
• type Linter
• type Project
• type ProjectReport
• type Report
  • func MergeReports(finalReport Report, reports ...Report) Report
  • func NewReport() Report
  • func (r Report) OverallScore() float64
• type Rule
  • func NewCustomRule(cr config.CustomRule) Rule
  • func (r *Rule) Disable()
  • func (r *Rule) Enable()

Functions

func Slug

func Slug(name string) string

Slug returns the given string, lowercased and with all spaces replaced by dashes.

Types

type CQLinter

type CQLinter interface {
	// String should return the human-text-friendly name of this linter
	fmt.Stringer

	Type() CQLinterType

	// DependencyName returns the name of the PyPI package that implements this linter
	DependencyName() string

	// IsConfigured returns true if there is a configuration for this linter in the given project,
	// regardless of whether this is a proper and clean configuration.
	IsConfigured(project Project) bool

	// IsProperlyConfigured returns true if the project is properly configured.
	IsProperlyConfigured(project Project) bool

	// IsInstalled returns true if the linter is installed (e.g. its executable is on PATH),
	// such that Run() can be called without errorring.
	IsInstalled() bool

	// Run runs the linter on the project, collects the issues that it reports and returns them,
	// or an error if that failed.
	Run(project Project) ([]CQLinterResult, error)
}

type CQLinterResult

type CQLinterResult interface {
	fmt.Stringer
}

type CQLinterType

type CQLinterType string

type Category

type Category struct {
	Name        string
	Slug        string
	Description string
}

func (Category) String

func (c Category) String() string

type Configurable

type Configurable interface {
	// Configure the implementing struct with the config. Return a non-nil error if there is a problem with how
	// mllint is configured. E.g. if a configuration option for this linter has a value that is outside of valid ranges.
	Configure(conf *config.Config) error
}

Configure should be implemented such that the struct that implements it configures itself to use the settings from the config object. If implemented on a Linter, this will be called before LintProject is called.

type ConfigurableLinter

type ConfigurableLinter interface {
	Linter
	Configurable
}

ConfigurableLinter is simply a Linter that also implements Configurable.

type DependencyManager

type DependencyManager interface {
	// Dependencies returns a list of the names of all Python dependencies that this manager is tracking.
	Dependencies() []string

	// HasDependency should return true if this dependency manager is tracking this dependency.
	// This means it can either be in the regular dependencies, or dev dependencies.
	HasDependency(dependency string) bool

	// HasDevDependency should only return true if this dependency manager is tracking this dependency in its dev dependencies.
	HasDevDependency(dependency string) bool

	// Type returns the type of this DependencyManager.
	Type() DependencyManagerType
}

type DependencyManagerList

type DependencyManagerList []DependencyManager

func (DependencyManagerList) Contains

func (list DependencyManagerList) Contains(target DependencyManager) bool

func (DependencyManagerList) ContainsAllTypes

func (list DependencyManagerList) ContainsAllTypes(targets ...DependencyManagerType) bool

func (DependencyManagerList) ContainsType

func (list DependencyManagerList) ContainsType(target DependencyManagerType) bool

func (DependencyManagerList) Main

func (list DependencyManagerList) Main() DependencyManager

Main returns the first dependency manager in the list, under the assumption that that is the main / primary dependency manager used in the project.

type DependencyManagerType

type DependencyManagerType interface {
	fmt.Stringer

	// Detect whether a project is using this type of dependency manager and return the dependency manager instantiated for this project if it is detected,
	// or an error if it is not detected.
	//
	// Generally, this is done by detecting whether the manager's configuration file exists.
	Detect(project Project) (DependencyManager, error)
}

type GitInfo

type GitInfo struct {
	// the URL of the Git remote, e.g. `git@github.com:bvobart/mllint.git`
	RemoteURL string
	// the hash of the current commit.
	Commit string
	// the name of the current branch.
	Branch string
	// whether the repository is currently in a dirty state (i.e. files added / removed / changed)
	Dirty bool
}

GitInfo describes some info about the Git repository that a project is in.

type Linter

type Linter interface {
	// Name of the linter
	Name() string

	// Rules returns all the rules that this linter can check while linting a project
	Rules() []*Rule

	// LintProject is the main method that runs this linter. It will receive the full path to the
	// directory in which the project is located. It is then expected to perform its respective analysis
	// and return a Report or an error if there was one.
	//
	// The returned Report should contain a mapping of each checked Rule to a percentual score between 0 and 100.
	// A linter may also add additional details to a report related to a specific rule, which is especially
	// recommended if the rule scored less than 100.
	LintProject(project Project) (Report, error)
}

Linter is the main interface for a struct that defines a linter over a certain category. There must be one Linter per Category, which may be a linters.CompositeLinter that employs several other Linters to subdivide checking all the rules within that category. It is recommended to implement this interface as a struct with methods that have pointer receivers.

type Project

type Project struct {
	// The project's assumed root directory, absolute path.
	Dir string
	// Information about the project's Git repository.
	Git GitInfo
	// mllint's configuration for this project
	Config config.Config
	// Type of mllint configuration
	ConfigType config.FileType
	// Dependency managers that this project uses, e.g. requirements.txt, Poetry or Pipenv
	DepManagers DependencyManagerList
	// Code Quality linters that this project uses, i.e. static analysis tools that focus on analysing code, such as Pylint, Mypy and Bandit.
	CQLinters []CQLinter
	// Absolute paths to the Python files that are in this project's repository
	PythonFiles utils.Filenames
}

Project contains general information about the project that will be filled in before the linters start their analysis.

type ProjectReport

type ProjectReport struct {
	Project
	Reports map[Category]Report
	Errors  *multierror.Error
}

ProjectReport is what you end up with after mllint finishes analysing a project.

type Report

type Report struct {
	// Scores maps each evaluated rule to a score
	Scores map[Rule]float64

	// Details contains any additional details to accompany a Rule's evaluation.
	// Typically, when a Linter detects that a project does not conform to a Rule,
	// it will want to provide some form of reasoning about it, pointers to which
	// parts of the project repo the Rule violation occcurs in, and what the user can
	// do to fix the issue.
	//
	// The mapped string may be formatted using Markdown.
	Details map[Rule]string
}

Report is the type of object returned by a Linter after linting a project.

func MergeReports

func MergeReports(finalReport Report, reports ...Report) Report

func NewReport

func NewReport() Report

func (Report) OverallScore

func (r Report) OverallScore() float64

OverallScore returns the weighted average of the scores of each rule, weighted with each rule's respective weight.

type Rule

type Rule struct {
	// Slug should be a lowercased, dashed reference code, e.g. 'git-no-big-files'
	Slug string

	// Name should be a short sentence (<10 words) that concisely describes what this rule expects,
	// e.g. '.dvc folder should be comitted to Git' or 'Project should not use Git to track large files'
	Name string

	// Details should contain a longer, descriptive, Markdown-formatted text that explains the reasoning behind this rule,
	// as well as provide background info on the subject and pointers on how to fix violations of the rule.
	Details string

	// Weight determines the weight of this rule's score within its respective category.
	Weight float64 // TODO: figure out what to with this...

	// Whether this rule was explicitly disabled by the user.
	Disabled bool
}

Rule is a struct for defining what a rule looks like that `mllint` will check.

func NewCustomRule

func NewCustomRule(cr config.CustomRule) Rule

NewCustomRule creates a new rule based on a custom rule definition as can be configured in `mllint`'s config

func (*Rule) Disable

func (r *Rule) Disable()

func (*Rule) Enable

func (r *Rule) Enable()