eco-pro / project-metadata-utils / Elm.Error

When elm make --report=json fails, this module helps you turn the resulting JSON into HTML.

Compile Errors

decoder : Json.Decode.Decoder Error

Decode the JSON produced when elm make --report=json fails. The goal is to get the data in a format that can be presented in HTML.

Note: Please follow the design advice in the rest of the docs, like for Chunk and Color. Consistent presentation of errors means that once you learn how to read errors, you have that ability with any tool you use in Elm.


type Error
    = GeneralProblem ({ path : Maybe String, title : String, message : List Chunk })
    | ModuleProblems (List BadModule)

When elm make --report=json fails, there are two major categories of error. Usually you have ModuleProblems like an unknown variable name or type mismatch, but you can also get a GeneralProblem like cyclic modules or an invalid elm.json file. The latter are much less common, but because they never have a Region they need to be handled separately.


type alias BadModule =
{ path : String
, name : String
, problems : List Problem 
}

When I cannot compile a module, I am able to report a bunch of problems at once. So you may see a bunch of naming errors or type errors.


type alias Problem =
{ title : String
, region : Region
, message : List Chunk 
}

A problem in an Elm module.

Styled Text


type Chunk
    = Unstyled String
    | Styled Style String

A chunk of text to show. Chunks will contain newlines here and there, so I recommend using white-space: pre to make sure everything looks alright.

The error messages are designed to look nice in 80 columns, and the only way any line will be longer than that is if a code snippet from the user is longer. Anyway, please try to get a presentation that matches the terminal pretty well. It will look alright, and the consistency will be more valuable than any small changes.


type alias Style =
{ bold : Basics.Bool
, underline : Basics.Bool
, color : Maybe Color 
}

Widely supported styles for ANSI text. Bold and underline are used very rarely in Elm output. Mainly for a Note or a Hint about something. Colors are used relatively infrequently, primarily to draw attention to the most important information. Red is the problem, yellow is distilled advice, etc.


type Color
    = Red
    | RED
    | Magenta
    | MAGENTA
    | Yellow
    | YELLOW
    | Green
    | GREEN
    | Cyan
    | CYAN
    | Blue
    | BLUE
    | White
    | WHITE
    | Black
    | BLACK

Error messages use colors to emphasize the most useful information. This helps people resolve their problems quicker! Because the errors need to work on the terminal as well, the colors are limited to ANSI colors that are widely supported by different terminal softwark.

So there are eight colors, each with a Dull and VIVID version.

Note: I have tried to make the meaning of each color consistent across all error messages (red is problem, yellow is decent advice, green is great advice, cyan is helpful information, etc.) so please use colors that actually match the color names! I think consistency is worth a lot within the ecosystem.

Code Regions


type alias Region =
{ start : Position
, end : Position 
}

Every Problem is caused by code in a specific Region.


type alias Position =
{ line : Basics.Int
, column : Basics.Int 
}

A line and column in the source file. Both are one-indexed, so every file starts at { line = 1, column = 1 } and increases from there.