add readme

1 files changed, 107 insertions, 0 deletions

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..1f4b17d
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,107 @@
+# 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:
+
+```purescript
+-- | 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
+  }
+
+```