Stan.Config

stan runtime configuration that allows customizing the set of inspections to check the code against.

Data types

data ConfigP (p :: Phase Text)

Main configuration type for the following purposes:

• Filtering inspections (including or ignoring) per scope (file, directory, all)

Constructors

ConfigP

Fields

• configChecks :: !(p ::- [Check])
• configRemoved :: !(p ::- [Scope])
• configIgnored :: !(p ::- [Id Observation])

Instances

Semigroup PartialConfig

Defined in Stan.Config

Methods

(<>) :: PartialConfig -> PartialConfig -> PartialConfig

sconcat :: NonEmpty PartialConfig -> PartialConfig

stimes :: Integral b => b -> PartialConfig -> PartialConfig

(Eq (p ::- [Check]), Eq (p ::- [Scope]), Eq (p ::- [Id Observation])) => Eq (ConfigP p)

Defined in Stan.Config

Methods

(==) :: ConfigP p -> ConfigP p -> Bool

(/=) :: ConfigP p -> ConfigP p -> Bool

(Show (p ::- [Check]), Show (p ::- [Scope]), Show (p ::- [Id Observation])) => Show (ConfigP p)

Defined in Stan.Config

Methods

showsPrec :: Int -> ConfigP p -> ShowS

show :: ConfigP p -> String

showList :: [ConfigP p] -> ShowS

type Config = ConfigP 'Final

type PartialConfig = ConfigP 'Partial

data Check

Rule to control the set of inspections per scope.

Constructors

Check

Fields

• checkType :: !CheckType
• checkFilter :: !CheckFilter
• checkScope :: !Scope

Instances

Eq Check

Defined in Stan.Config

Methods

(==) :: Check -> Check -> Bool

(/=) :: Check -> Check -> Bool

Show Check

Defined in Stan.Config

Methods

showsPrec :: Int -> Check -> ShowS

show :: Check -> String

showList :: [Check] -> ShowS

data CheckType

Type of Check: Include or Exclude Inspections.

Constructors

Include

Exclude

Instances

Bounded CheckType

Defined in Stan.Config

Methods

minBound :: CheckType

maxBound :: CheckType

Enum CheckType

Defined in Stan.Config

Methods

succ :: CheckType -> CheckType

pred :: CheckType -> CheckType

toEnum :: Int -> CheckType

fromEnum :: CheckType -> Int

enumFrom :: CheckType -> [CheckType]

enumFromThen :: CheckType -> CheckType -> [CheckType]

enumFromTo :: CheckType -> CheckType -> [CheckType]

enumFromThenTo :: CheckType -> CheckType -> CheckType -> [CheckType]

Eq CheckType

Defined in Stan.Config

Methods

(==) :: CheckType -> CheckType -> Bool

(/=) :: CheckType -> CheckType -> Bool

Show CheckType

Defined in Stan.Config

Methods

showsPrec :: Int -> CheckType -> ShowS

show :: CheckType -> String

showList :: [CheckType] -> ShowS

data CheckFilter

Criterion for inspections filtering.

Constructors

CheckInspection !(Id Inspection)

CheckSeverity !Severity

CheckCategory !Category

CheckAll

Instances

Eq CheckFilter

Defined in Stan.Config

Methods

(==) :: CheckFilter -> CheckFilter -> Bool

(/=) :: CheckFilter -> CheckFilter -> Bool

Show CheckFilter

Defined in Stan.Config

Methods

showsPrec :: Int -> CheckFilter -> ShowS

show :: CheckFilter -> String

showList :: [CheckFilter] -> ShowS

data Scope

Where to apply the rule for controlling inspection set.

Constructors

ScopeFile !FilePath

ScopeDirectory !FilePath

ScopeAll

Instances

Eq Scope

Defined in Stan.Config

Methods

(==) :: Scope -> Scope -> Bool

(/=) :: Scope -> Scope -> Bool

Show Scope

Defined in Stan.Config

Methods

showsPrec :: Int -> Scope -> ShowS

show :: Scope -> String

showList :: [Scope] -> ShowS

Default

defaultConfig :: PartialConfig

mkDefaultChecks :: [FilePath] -> HashMap FilePath (HashSet (Id Inspection))

Final stage

finaliseConfig :: PartialConfig -> Trial Text Config

Printing

configToCliCommand :: Config -> Text

Convert TOML configuration to the equivalent CLI command that can be copy-pasted to get the same results as using the TOML config.

  ⓘ Reading Configurations from /home/vrom911/Kowainik/stan/.stan.toml ...
stan check --exclude --directory=test/ \
     check --include \
     check --exclude --inspectionId=STAN-0002 \
     check --exclude --inspectionId=STAN-0001 --file=src/MyFile.hs
     remove --file=src/Secret.hs
     ignore --id="STAN0001-asdfgh42:42"

Apply config

The applyConfig function transforms the list of rules defined in the Config (either via TOML or CLI) to get the list of Inspections for each module.

By default, stan runs all Inspections for all modules in the Haskell project and outputs all Observations it finds. Using Config, you can adjust the default setting using your preferences.

Algorithm

The algorithm for figuring out the resulting set of Inspections per module applies each Check one-by-one in order of their appearance.

When introducing a new Check in the config, you must always specify three key-value pairs:

1. CheckType — control inclusion and exclusion criteria

   • Include

     type = "Include"
     

   • Exclude

     type = "Exclude"
     

2. CheckFilter — how to filter inspections

   • CheckInspection: by specific Inspection Id

     id = "STAN-0001"
     

   • CheckSeverity: by specific Severity

     severity = "Warning"
     

   • CheckCategory: by specific Category

     category = "Partial"
     

   • CheckAll: applied to all Inspections

     filter = "all"
     

3. Scope — where to apply check

   • ScopeFile: only to the specific file

     file = "src/MyModule.hs"
     

   • ScopeDirectory: to all files in the specified directory

     directory = "text/"
     

   • ScopeAll: to all files

     scope = "all"
     

The algorithm doesn't remove any files or inspections from the consideration completely. So, for example, if you exclude all inspections in a specific file, new inspections can be added for this file later by the follow up rules.

However, if you want to completely remove some files or directory from analysis, you can use the remove key:

[[remove]]
file = "src/Autogenerated.hs"

Common examples

This section contains examples of custom configuration (in TOML) for common cases.

1. Exclude all Inspections.

   [[check]]
   type   = "Exclude"
   filter = "all"
   scope  = "all"
   

2. Exclude all Inspections only for specific file.

   [[check]]
   type = "Exclude"
   filter = "all"
   file = "src/MyModule.hs"
   

3. Exclude a specific Inspection in all files:

   [[check]]
   type = "Exclude"
   id = "STAN-0001"
   scope = "all"
   

4. Exclude all Inspections for specific file except Inspections that have a category Partial.

   # exclude all inspections for a file
   [[check]]
   type = "Exclude"
   filter = "all"
   file = "src/MyModule.hs"
   
   # return back only required inspections
   [[check]]
   type = "Include"
   category = "Partial"
   file = "src/MyModule.hs"
   

5. Keep Inspections only with the category Partial for all files except a single one.

   # exclude all inspections
   [[check]]
   type   = "Exclude"
   filter = "all"
   scope  = "all"
   
   # return back inspections with the category Partial
   [[check]]
   type = "Include"
   category = "Partial"
   scope = "all"
   
   # finally, disable all inspections for a specific file
   [[check]]
   type = "Exclude"
   filter = "all"
   file = "src/MyModule.hs"
   

applyConfig

Arguments

:: [FilePath]

Paths to project files

-> Config

Stan runtime configuration

-> HashMap FilePath (HashSet (Id Inspection))

Resulting set of inspections for each file

Apply configuration to the given list of files to get the set of inspections for each file.

The algorithm:

1. Remove all files specified by the remove option.
2. Run applyChecks on the remaining files.

applyChecks

Arguments

:: [FilePath]

Paths to project files

-> [Check]

List of rules

-> HashMap FilePath (HashSet (Id Inspection))

Resulting set of inspections for each file

Convert the list of Checks from Config to data structure that allows filtering of Inspections for given files.

applyChecksFor

Arguments

:: HashMap FilePath (HashSet (Id Inspection))

Initial set of inspections for each file

-> [Check]

List of rules

-> HashMap FilePath (HashSet (Id Inspection))

Resulting set of inspections for each file

Modify existing Checks for each file using the given list of Checks.