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

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:

-- | 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
  }