# walint: lint & adjust workadventure maps

`walint` is intended as a simple linter that will check workadventure maps for
common errors, such as non-existent map entrypoints or missing asset files, and
additionally suggest changes to improve accessability.

Optionally, it can also *adjust* maps — e.g. to automatically insert property 
values or help enforce an event's map policies — and then write them out again,
copying all needed assets and minifying the map's json.

## Usage
``` sh
walint --config-file config.json --repository path \
      [--out path] [--json] [--pretty] [--entrypoint main.json]

```

### Options
 - `--repository`: path to a map repository
 - `--entrypoint`: entrypoint of a map repository, i.e. a tiled map in its root
   directory. `walint` will lint all maps reachable from it. If not given, it
   defaults to `main.json`
 - `--lintLevel`: limit output only to messages that have at most the given
   level. Valid levels are `Info`, `Suggestion`, `Warning`, `Error`, `Fatal`.
   Defaults to `Suggestion` if not given.
 - `--json`: print output as json instead of the normal more human-friendly format
 - `--pretty`: if used with `--json`, insert line breaks and indentation to make
   the output more readable. Otherwise no effect.
 - `--out path`: write the linted & adjusted repository to the given path. Any
   json written to this path will be minimised, and *only those maps and assets
   which are reachable from the entrypoint* will be writen at all. If not given,
   `walint` will only run the linter and do nothing else. If `walint` encounters
   any references to local map assets which are not present in the repository, it
   will fail.
 - `--config-file file`: path to a configuation file. Required (for now).
 - `--config json`: takes a string which should contain a json object conforming
   to the same schema as the configuration file, except that all keys are 
   optional. Keys given here will override whatever values are set in the 
   configuration file.

### Configuation
Take a look at `config.json` for an example. Most keys are required, and do not
have default values.

For the schema, take a look at the definition of the `LintConfig` type in
`lib/LintConfig.hs`; I'll attempt to remember documenting options there (if you
are unfamiliar with Haskell: key names come first, though there are all prepended
with `config` here. Types come after the `::`; ignore the `HKD f` bit and look
at whatever comes after that. Most types should be self-explanatory; Note that
you may leave out keys whose type includes `Maybe`)


### Output
By default `walint` prints lints in a hopefully human-readable manner. If the
`--json` option is given, it will instead give a json that should conform to
the following schema:

```haskell
-- | The main type of walint's output
type Output = 
  { mapLints :: Map FilePath MapLint
  -- ^ an object of per-map lints. Each key is a filepath from the repository's root
  , missingAssets :: List Asset
  -- ^ a list of missing assets
  , missingDeps :: List Entrypoint
  -- ^ a list of other missing dependencies (for now, just entrypoints)
  }

-- | An object containing map lints
type MapLint =
  { general :: List Lint 
  -- ^ general lints (most often empty)
  , layer :: Map Message Where
  -- ^ an object of per-layer lints. Each key is a lint message
  , tileset :: Map Message Where
  -- ^ an object of per-tileset lints. Again, each key is a lint message
  }

-- | Further desription of a single lint
type Where =
  { in :: List String
  -- ^ where did this lint occur? (list of layers / tileset names)
  , level :: Level
  -- ^ what is this lint's level?
  }
  
-- | Valid lint levels. Encoded as strings.
data Level = Info | Suggestion | Warning | Error | Fatal


-- | description of a single (missing) asset
type Asset =
  { asset :: FilePath
  -- ^ the filename, as referenced somewhere within the repository
  , neededBy :: List FilePath
  -- ^ list of filenames of maps which reference this asset
  }

-- | description of a single (missing) entrypoint
type Entrypoint =
  { entrypoint :: String
  -- ^ the entrypoint, as a string, e.g. path/to/map#entrypoint
  , neededBy :: List FilePath 
  -- ^ list of filenames of maps which reference this entrypoint
  }

```