Specify where you don't want errors to be reported in, as posix paths:

• external libraries you copied over and don't want to modify more than necessary
• generated source code which isn't supposed to be read and or over which you have little control
• you wrote a check that is very specific and should only be applied for a portion of your codebase

(tests/ is never implicitly inspected since it's a standalone gren project)

To write a new Check you need to

• inspectModule: collect knowledge from module syntax. More info below
• inspectGrenJson: collect knowledge from the gren.json project config. You can use the raw source to search for a section you want to highlight in an Error
• inspectExtraFile: collect knowledge from an available files like README.md, CHANGELOG.md or package.json that aren't source modules or the gren.json. The provided path is relative to the project's gren.json and can be used as an Error target file path
• inspectDirectDependencies: collect knowledge from all packages and their modules the project directly depends on
• knowledgeMerge: combine collected knowledge from different parts
• report: evaluate your combined knowledge and provide errors

For inspectModule, the path is relative to the project's gren.json and can be used as an Error target file path.

The raw gren file source can be used to preserve existing formatting in a region in when you want to move and copy things around, see sourceExtractInRegion.

The syntax field contains a tree-like structure which represents your source code: Compiler.Ast.Source.Module. I recommend having the documentation for that package open while writing a check.

The module's import statements (import Html as H exposing (div)) in order of their definition.

An example check that forbids importing both Element and Html.Styled in the same module:

import SourcePosition
import ExtraCheck
import Dict
import Array.Builder

check : ExtraCheck.Check
check =
    ExtraCheck.create
        { inspectModule =
            \moduleData ->
                let
                    importedModuleNames : Dict String SourcePosition.Region
                    importedModuleNames =
                        moduleData.syntax.imports
                            |> Array.foldl
                                (\{ value = import_ } soFar ->
                                    soFar
                                        |> Dict.set import_.module_.value
                                            (import_.module_ |> ExtraCheck.locatedRegion)
                                )
                                Dict.empty
                in
                when
                    Maybe.map2 (\elementImportRegion _ -> elementImportRegion)
                        (importedModuleNames |> Dict.get "Element")
                        (importedModuleNames |> Dict.get "Html.Styled")
                is
                    Just elementImportRegion ->
                        Dict.singleton moduleData.path elementImportRegion

                    _ ->
                        Dict.empty
        , inspectDirectDependencies = \_ -> Dict.empty
        , inspectGrenJson = \_ -> Dict.empty
        , inspectExtraFile = \_ -> Dict.empty
        , knowledgeMerge = \a b -> Dict.union a b
        , report =
            \invalidImportsByPath ->
                invalidImportsByPath
                    |> Dict.foldl
                        (\{ key = path, value = elementImportRegion } soFar ->
                            soFar
                                |> Array.Builder.pushLast
                                    { path = moduleData.path
                                    , message = "both `Element` and `Html.Styled` used"
                                    , details = "At fruits.com, we use `Element` in the dashboard application, and `Html.Styled` in the rest of the code. We want to use `Element` in our new projects, but in projects using `Html.Styled`, we don't want to use both libraries to keep things simple."
                                    , region = elementImportRegion
                                    , fix = []
                                    }
                        )
                        (Array.Builder.empty 0)
                    |> Array.Builder.toArray
        }

For more complex examples of checks, check out the checks in this package like DebugIsNotUsed.check

Relative path to the project gren.json to be used in an Error or expected test error. Constant for "gren.json"

Insert something at the given position

Remove the section in between a given region

Replace the section in between a given region by something

Walk immediate child-expressions, collecting information on the way. To additionally track locally introduced variables, use expressionImmediateSubsFoldWithIntroducedVariables

Walk immediate child-expressions, tracking what new bindings have been added to the name scope for each sub-expression, collecting information on the way.

Don't forget to include function declaration parameter variables in the given dict using patternArrayVariablesFold.

Knowing local variable names in all parts of an expression is useful for knowing if a variable refers to an import-exposed (or implicitly imported) name or is unrelated. When you want to fix code by inserting references like identity, first check for local variables and if necessary insert Basics/WhateverImportAliasIsUsed.identity instead.

Note that in these cases, you also need to check for module-declared variable names first.

Walk immediate child-patterns, collecting information on the way

Walk immediate child-patterns, collecting information on the way

Fold over all the bindings contained (deep) within the given pattern. Typically used with patternVariablesFold Dict.set currentLocalVariables pattern

Fold over all the bindings contained (deep) within the given patterns. Typically used with patternArrayVariablesFold Dict.set Dict.empty declarationParameters

Package the start and end positions of a located syntax node into a SourcePosition.Region.

replaceExpressionByEmptyArrayFix : Compiler.Ast.Source.Expression -> ExtraCheck.SourceEdit
replaceExpressionByEmptyArrayFix =
    ExtraCheck.replaceRegion
        (expression |> ExtraCheck.locatedRegion)
        "[]"

In when you need the read the source in a region as formatted by the user. This can be nice to keep the user's formatting if you just move code around

Find all occurrences of a given section in the source in the when you can't access or easily calculate the region. Use sparingly

Convert an offset into the source (measured in units) into a region. Use sparingly

The set of modules in the exposed-modules field in a package gren.json. Only use this helper if you need a set, otherwise prefer outlineExposedModuleNames which produces an array and is faster.

The module names listed in the exposed-modules field in a package gren.json. If you need a set, use outlineExposedModuleNameSet

From the gren-lang/core readme:

The modules in this package are so common, that some of them are imported by default in all Gren files. So it is as if every Gren file starts with these imports:

import Basics exposing (..)
import Array exposing (Array)
import Maybe exposing (Maybe(..))
import Result exposing (Result(..))
import String exposing (String)
import Char exposing (Char)

import Debug

import Platform exposing (Program)
import Platform.Cmd as Cmd exposing (Cmd)
import Platform.Sub as Sub exposing (Sub)

Run a Check on a project, matching all reported module errors, gren.json errors and extra file errors with your provided expected errors.

import DebugForbid
import ExtraCheck
import Test

tests : Test.Test
tests =
    Test.describe "DebugForbid"
        [ Test.test "report Debug.log use"
            (\{} ->
                { check = DebugForbid.check
                , projectConfiguration = ExtraCheck.applicationConfigurationMinimal
                , files =
                    [ { path = "src/A.gren"
                        , source =
                            """
                            module A exposing (a)
                            import Html
                            a =
                                Debug.log "some" "message"
                            """
                        }
                    ]
                }
                    |> ExtraCheck.expectToReport
                        [ { path = "src/A.gren"
                          , message = "Remove the use of `Debug` before shipping to production"
                          , details = "Compiling gren code in optimized mode does not allow these helpers."
                          , region = ExtraCheck.ExpectUnder "Debug.log"
                          , fixedFiles =
                                [ { path = "src/A.gren"
                                  , source =
                                        """
                                        module A exposing (a)
                                        a =
                                            "message"
                                        """
                                  }
                                ]
                          }
                        ]
            )
        ]

To expect no errors, use ... |> expectToReport [].

You can also specify a custom project config for when you want to test a package, use a custom gren.json or add dependencies by supplying the raw sources for the gren.json and the direct dependency modules (the most common gren-lang/core modules are automatically part of every tested project).

If you find that these tests are overly verbose, I encourage you to create local helpers. I personally prefer that over exposing these from the ExtraCheck module, as trying to make assumptions about your most common test scenarios seems questionable to me.

The default project after gren init --platform=common (no browser/node dependencies). Equivalent to (copy and adapt if necessary)

{ grenJson =
    """
    {
        "type": "application",
        "platform": "common",
        "source-directories": [
            "src"
        ],
        "gren-version": "0.6.3",
        "dependencies": {
            "direct": {
                "gren-lang/core": "7.4.0"
            },
            "indirect": {}
        }
    }
    """
, directDependencies = []
}

(the most common gren-lang/core modules are automatically part of every tested project)

ExtraCheck a given project and return the errors reported by the given Check as a dict along with a next Run that uses cached knowledge wherever it can.

import ExtraCheck
import SomeConvention

doCheck =
    let
        project =
            { ignoreErrorsForPathsWhere = SomeConvention.check.ignoreErrorsForPathsWhere
            , addedOrChangedModules =
                [ { path = "src/A.gren", source = "module A exposing (a)\na = 1", syntax = ... }
                , { path = "src/B.gren", source = "module B exposing (b)\nb = 1", syntax = ... }
                ]
            , ...
            }

        runResult =
            ExtraCheck.run SomeConvention.check.run project
    in
    doSomethingWith runResult.errorsByPath

The resulting next Run internally keeps a cache to make it faster to re-run the check when only some files have changed. You can store this resulting nextRun in your application state type, e.g.

ExtraCheck.run
    yourApplicationState.nextRunProvidedByTheLastCheckRun
    SomeConvention.check.ignoreErrorsForPathsWhere
    { addedOrChangedModules =
        [ { path = "src/C.gren", source = "module C exposing (c)\nc = 1", syntax = ... }
        ]
    , removedModulePaths = [ "src/B.gren" ]
    , ...
    }

Try to apply a set of SourceEdites to the relevant file source, potentially failing with a SourceEditError