api

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 interface {
	fmt.Stringer
}

type CQLinterType string

type Category struct {
	Name        string
	Slug        string
	Description string
}

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
}

type ConfigurableLinter interface {
	Linter
	Configurable
}

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 []DependencyManager

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 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
}

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)
}

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
}

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

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
}

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
}