diff options
| -rw-r--r-- | Readme.md | 107 | ||||
| -rw-r--r-- | src/Main.hs | 5 |
2 files changed, 111 insertions, 1 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 + } + +``` diff --git a/src/Main.hs b/src/Main.hs index 5b8b66f..be28f07 100644 --- a/src/Main.hs +++ b/src/Main.hs @@ -37,8 +37,11 @@ data Options = Options , pretty :: Bool -- ^ pretty-print the json to make it human-readable , out :: Maybe String - , config :: Maybe (LintConfig Maybe) + -- ^ path to write the (possibly adjusted) maps to after linting , configFile :: Maybe FilePath + -- ^ path to a config file. Currently required. + , config :: Maybe (LintConfig Maybe) + -- ^ a "patch" for the configuration file } deriving (Show, Generic, HasArguments) |