stan-0.2.0.0: Haskell STatic ANalyser

Copyright | (c) 2020 Kowainik
License | MPL-2.0
Maintainer | Kowainik <xrom.xkov@gmail.com>
Safe Haskell | None
Language | Haskell2010

Stan.Config

Contents

- Data types
- Default
- Final stage
- Printing
- Apply config

Description

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

Synopsis

- data ConfigP (p :: Phase Text) = ConfigP {
  - configChecks :: !(p ::- [Check])
  - configRemoved :: !(p ::- [Scope])
  - configIgnored :: !(p ::- [Id Observation])
  }
- type Config = ConfigP ('Final :: Phase Text)
- type PartialConfig = ConfigP ('Partial :: Phase Text)
- data Check = Check {
  - checkType :: !CheckType
  - checkFilter :: !CheckFilter
  - checkScope :: !Scope
  }
- data CheckType
  - = Include
  - | Exclude
- data CheckFilter
  - = CheckInspection !(Id Inspection)
  - | CheckSeverity !Severity
  - | CheckCategory !Category
  - | CheckAll
- data Scope
  - = ScopeFile !FilePath
  - | ScopeDirectory !FilePath
  - | ScopeAll
- defaultConfig :: PartialConfig
- mkDefaultChecks :: [FilePath] -> HashMap FilePath (HashSet (Id Inspection))
- finaliseConfig :: PartialConfig -> Trial Text Config
- configToCliCommand :: Config -> Text
- applyConfig :: [FilePath] -> Config -> HashMap FilePath (HashSet (Id Inspection))
- applyChecks :: [FilePath] -> [Check] -> HashMap FilePath (HashSet (Id Inspection))
- applyChecksFor :: HashMap FilePath (HashSet (Id Inspection)) -> [Check] -> HashMap FilePath (HashSet (Id Inspection))

# 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

Instances details

Semigroup PartialConfig # |
Instance details Defined in Stan.Config Methods (<>) :: PartialConfig -> PartialConfig -> PartialConfig # sconcat :: NonEmpty PartialConfig -> PartialConfig # stimes :: Integral b => b -> PartialConfig -> PartialConfig #
(Show (p ::- [Check]), Show (p ::- [Scope]), Show (p ::- [Id Observation])) => Show (ConfigP p) # |
Instance details Defined in Stan.Config Methods showsPrec :: Int -> ConfigP p -> ShowS # show :: ConfigP p -> String # showList :: [ConfigP p] -> ShowS #
(Eq (p ::- [Check]), Eq (p ::- [Scope]), Eq (p ::- [Id Observation])) => Eq (ConfigP p) # |
Instance details Defined in Stan.Config Methods (==) :: ConfigP p -> ConfigP p -> Bool # (/=) :: ConfigP p -> ConfigP p -> Bool #

type Config = ConfigP ('Final :: Phase Text) #

type PartialConfig = ConfigP ('Partial :: Phase Text) #

data Check #

Rule to control the set of inspections per scope.

Constructors

Check |
Fields checkType :: !CheckType checkFilter :: !CheckFilter checkScope :: !Scope

#### Instances

Instances details

Show Check # |
Instance details Defined in Stan.Config Methods showsPrec :: Int -> Check -> ShowS # show :: Check -> String # showList :: [Check] -> ShowS #
Eq Check # |
Instance details Defined in Stan.Config Methods (==) :: Check -> Check -> Bool # (/=) :: Check -> Check -> Bool #

data CheckType #

Type of `Check`: `Include` or `Exclude` `Inspection`s.

Constructors

Include |
Exclude |

#### Instances

Instances details

Bounded CheckType # |
Instance details Defined in Stan.Config Methods minBound :: CheckType # maxBound :: CheckType #
Enum CheckType # |
Instance details 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] #
Show CheckType # |
Instance details Defined in Stan.Config Methods showsPrec :: Int -> CheckType -> ShowS # show :: CheckType -> String # showList :: [CheckType] -> ShowS #
Eq CheckType # |
Instance details Defined in Stan.Config Methods (==) :: CheckType -> CheckType -> Bool # (/=) :: CheckType -> CheckType -> Bool #

data CheckFilter #

Criterion for inspections filtering.

Constructors

CheckInspection !(Id Inspection) |
CheckSeverity !Severity |
CheckCategory !Category |
CheckAll |

#### Instances

Instances details

Show CheckFilter # |
Instance details Defined in Stan.Config Methods showsPrec :: Int -> CheckFilter -> ShowS # show :: CheckFilter -> String # showList :: [CheckFilter] -> ShowS #
Eq CheckFilter # |
Instance details Defined in Stan.Config Methods (==) :: CheckFilter -> CheckFilter -> Bool # (/=) :: CheckFilter -> CheckFilter -> Bool #

data Scope #

Where to apply the rule for controlling inspection set.

Constructors

ScopeFile !FilePath |
ScopeDirectory !FilePath |
ScopeAll |

#### Instances

Instances details

Show Scope # |
Instance details Defined in Stan.Config Methods showsPrec :: Int -> Scope -> ShowS # show :: Scope -> String # showList :: [Scope] -> ShowS #
Eq Scope # |
Instance details Defined in Stan.Config Methods (==) :: Scope -> Scope -> Bool # (/=) :: Scope -> Scope -> Bool #

# 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 `Inspection`s for each module.

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

### Algorithm

The algorithm for figuring out the resulting set of `Inspection`s 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 `Inspection`s

         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 `Inspection`s.

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

2. Exclude all `Inspection`s 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 `Inspection`s for specific file except `Inspection`s 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 `Inspection`s 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 `Check`s from `Config` to data structure that allows filtering of `Inspection`s 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 `Check`s for each file using the given list of `Check`s.