stan-0.1.2.1: Haskell STatic ANalyser
Copyright(c) 2020 Kowainik
LicenseMPL-2.0
MaintainerKowainik <xrom.xkov@gmail.com>
Safe HaskellNone
LanguageHaskell2010

Stan.Config

Description

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

Synopsis

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

Instances

Instances details
Semigroup PartialConfig # 
Instance details

Defined in Stan.Config

(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 #

data Check #

Rule to control the set of inspections per scope.

Constructors

Check 

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 #

Constructors

Include 
Exclude 

Instances

Instances details
Bounded CheckType # 
Instance details

Defined in Stan.Config

Enum CheckType # 
Instance details

Defined in Stan.Config

Show CheckType # 
Instance details

Defined in Stan.Config

Eq CheckType # 
Instance details

Defined in Stan.Config

data CheckFilter #

Criterion for inspections filtering.

Instances

Instances details
Show CheckFilter # 
Instance details

Defined in Stan.Config

Eq CheckFilter # 
Instance details

Defined in Stan.Config

data Scope #

Where to apply the rule for controlling inspection set.

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

Final stage

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

  2. CheckFilter — how to filter inspections

  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.