v8r 3.1.0 → 4.0.0

package/CHANGELOG.md

@@ -1,12 +1,51 @@
 # Changelog
 
+## 📦 [4.0.0](https://www.npmjs.com/package/v8r/v/4.0.0) - 2024-08-19
+
+* **Breaking:** Change to the JSON output format. The `results` key is now an array instead of an object.
+  In v8r <4, `results` was an object mapping filename to result object. For example:
+  ```json
+  {
+    "results": {
+      "./package.json": {
+        "fileLocation": "./package.json",
+        "schemaLocation": "https://json.schemastore.org/package.json",
+        "valid": true,
+        "errors": [],
+        "code": 0
+      }
+    }
+  }
+  ```
+
+  In v8r >=4 `results` is now an array of result objects. For example:
+  ```json
+  {
+    "results": [
+      {
+        "fileLocation": "./package.json",
+        "schemaLocation": "https://json.schemastore.org/package.json",
+        "valid": true,
+        "errors": [],
+        "code": 0
+      }
+    ]
+  }
+  ```
+* Plugin system: It is now possible to extend the functionality of v8r by using or writing plugins. See https://chris48s.github.io/v8r/category/plugins/ for further information
+* Documentation improvements
+
+## 📦 [3.1.1](https://www.npmjs.com/package/v8r/v/3.1.1) - 2024-08-03
+
+* Allow 'toml' as an allowed value for parser in custom catalog
+
 ## 📦 [3.1.0](https://www.npmjs.com/package/v8r/v/3.1.0) - 2024-06-03
 
 * Add ability to configure a proxy using global-agent
 
 ## 📦 [3.0.0](https://www.npmjs.com/package/v8r/v/3.0.0) - 2024-01-25
 
-* Drop compatibility with node 16
+* **Breaking:** Drop compatibility with node 16
 * Add ability to validate Toml documents
 
 ## 📦 [2.1.0](https://www.npmjs.com/package/v8r/v/2.1.0) - 2023-10-23
@@ -15,7 +54,7 @@
 
 ## 📦 [2.0.0](https://www.npmjs.com/package/v8r/v/2.0.0) - 2023-05-02
 
-* Drop compatibility with node 14
+* **Breaking:** Drop compatibility with node 14
 * Upgrade glob and minimatch to latest versions
 * Tested on node 20
 

package/README.md

@@ -1,233 +1,13 @@
 # v8r
 
-![build](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/build-status.svg)
-![coverage](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/coverage.svg)
-![version](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/package-version.svg)
-![license](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/package-license.svg)
-![node](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/package-node-version.svg)
+[![build](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/build-status.svg)](https://github.com/chris48s/v8r/actions/workflows/build.yml?query=branch%3Amain)
+[![coverage](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/coverage.svg)](https://app.codecov.io/gh/chris48s/v8r)
+[![version](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/package-version.svg)](https://www.npmjs.com/package/v8r)
+[![license](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/package-license.svg)](https://www.npmjs.com/package/v8r)
+[![node](https://raw.githubusercontent.com/chris48s/v8r/badges/.badges/main/package-node-version.svg)](https://www.npmjs.com/package/v8r)
 
-v8r is a command-line JSON and YAML validator that uses [Schema Store](https://www.schemastore.org/) to detect a suitable schema for your input files based on the filename.
+v8r is a command-line validator that uses [Schema Store](https://www.schemastore.org/) to detect a suitable schema for your input files based on the filename.
 
-## Getting Started
+📦 Install the package from [NPM](https://www.npmjs.com/package/v8r)
 
-One-off:
-```bash
-npx v8r@latest <filename>
-```
-
-Local install:
-```bash
-npm install -g v8r
-v8r <filename>
-```
-
-## Usage Examples
-
-### Validating files
-
-v8r can validate JSON or YAML files. You can pass filenames or glob patterns:
-
-```bash
-# single filename
-$ v8r package.json
-
-# multiple files
-$ v8r file1.json file2.json
-
-# glob patterns
-$ v8r 'dir/*.yml' 'dir/*.yaml'
-```
-
-[DigitalOcean's Glob Tool](https://www.digitalocean.com/community/tools/glob) can be used to help construct glob patterns
-
-### Manually specifying a schema
-
-By default, v8r queries [Schema Store](https://www.schemastore.org/) to detect a suitable schema based on the filename.
-
-```bash
-# if v8r can't auto-detect a schema for your file..
-$ v8r feature.geojson
-✖ Could not find a schema to validate feature.geojson
-
-# ..you can specify one using the --schema flag
-$ v8r feature.geojson --schema https://json.schemastore.org/geojson
-ℹ Validating feature.geojson against schema from https://json.schemastore.org/geojson ...
-✔ feature.geojson is valid
-```
-
-### Using a custom catlog
-
-Using the `--schema` flag will validate all files matched by the glob pattern against that schema. You can also define a custom [schema catalog](https://json.schemastore.org/schema-catalog.json). v8r will search any custom catalogs before falling back to [Schema Store](https://www.schemastore.org/).
-
-```bash
-$ cat > my-catalog.json <<EOF
-{ "\$schema": "https://json.schemastore.org/schema-catalog.json",
-  "version": 1,
-  "schemas": [ { "name": "geojson",
-                 "description": "geojson",
-                 "url": "https://json.schemastore.org/geojson.json",
-                 "fileMatch": ["*.geojson"] } ] }
-EOF
-
-$ v8r feature.geojson -c my-catalog.json
-ℹ Found schema in my-catalog.json ...
-ℹ Validating feature.geojson against schema from https://json.schemastore.org/geojson ...
-✔ feature.geojson is valid
-```
-
-This can be used to specify different custom schemas for multiple file patterns.
-
-## Configuration
-
-v8r uses CosmiConfig to search for a configuration. This means you can specify your configuration in any of the following places:
-
-- `package.json`
-- `.v8rrc`
-- `.v8rrc.json`
-- `.v8rrc.yaml`
-- `.v8rrc.yml`
-- `.v8rrc.js`
-- `.v8rrc.cjs`
-- `v8r.config.js`
-- `v8r.config.cjs`
-
-v8r only searches for a config file in the current working directory.
-
-Example yaml config file:
-
-```yaml
-# - One or more filenames or glob patterns describing local file or files to validate
-# - overridden by passing one or more positional arguments
-patterns: ['*json']
-
-# - Level of verbose logging. 0 is standard, higher numbers are more verbose
-# - overridden by passing --verbose / -v
-# - default = 0
-verbose: 2
-
-# - Exit with code 0 even if an error was encountered. True means a non-zero exit
-#   code is only issued if validation could be completed successfully and one or
-#   more files were invalid
-# - overridden by passing --ignore-errors
-# - default = false
-ignoreErrors: true
-
-# - Remove cached HTTP responses older than cacheTtl seconds old.
-#   Specifying 0 clears and disables cache completely
-# - overridden by passing --cache-ttl
-# - default = 600
-cacheTtl: 86400
-
-# - Output format for validation results
-# - overridden by passing --format
-# - default = text
-format: "json"
-
-# - A custom schema catalog.
-#   This catalog will be searched ahead of any custom catalogs passed using
-#   --catalogs or SchemaStore.org
-#   The format of this is subtly different to the format of a catalog
-#   passed via --catalogs (which matches the SchemaStore.org format)
-customCatalog:
-    schemas:
-        - name: Custom Schema  # The name of the schema (required)
-          description: Custom Schema  # A description of the schema (optional)
-
-          # A Minimatch glob expression for matching up file names with a schema (required)
-          fileMatch: ["*.geojson"]
-
-          # A URL or local file path for the schema location (required)
-          # Unlike the SchemaStore.org format, which has a `url` key,
-          # custom catalogs defined in v8r config files have a `location` key
-          # which can refer to either a URL or local file.
-          # Relative paths are interpreted as relative to the config file location.
-          location: foo/bar/geojson-schema.json
-
-          # A custom parser to use for files matching fileMatch
-          # instead of trying to infer the correct parser from the filename (optional)
-          # This property is specific to custom catalogs defined in v8r config files
-          parser: json5
-```
-
-The config file format is specified more formally in a JSON Schema:
-
-- [machine-readable JSON](config-schema.json)
-- [human-readable HTML](https://json-schema-viewer.vercel.app/view?url=https%3A%2F%2Fraw.githubusercontent.com%2Fchris48s%2Fv8r%2Fmain%2Fconfig-schema.json&show_breadcrumbs=on&template_name=flat)
-
-## Configuring a Proxy
-
-It is possible to configure a proxy via [global-agent](https://www.npmjs.com/package/global-agent) using the `GLOBAL_AGENT_HTTP_PROXY` environment variable:
-
-```bash
-export GLOBAL_AGENT_HTTP_PROXY=http://myproxy:8888
-```
-
-## Exit codes
-
-* v8r always exits with code `0` when:
-    * The input glob pattern(s) matched one or more files, all input files were validated against a schema, and all input files were **valid**
-    * `v8r` was called with `--help` or `--version` flags
-
-* By default v8r exits with code `1` when an error was encountered trying to validate one or more input files. For example:
-    * No suitable schema could be found
-    * An error was encountered during an HTTP request
-    * An input file was not JSON or yaml
-    * etc
-
-    This behaviour can be modified using the `--ignore-errors` flag. When invoked with `--ignore-errors` v8r will exit with code `0` even if one of these errors was encountered while attempting validation. A non-zero exit code will only be issued if validation could be completed successfully and the file was invalid.
-
-* v8r always exits with code `97` when:
-    * There was an error loading a config file
-    * A config file was loaded but failed validation
-
-* v8r always exits with code `98` when:
-    * An input glob pattern was invalid
-    * An input glob pattern was valid but did not match any files
-
-* v8r always exits with code `99` when:
-    * The input glob pattern matched one or more files, one or more input files were validated against a schema and the input file was **invalid**
-
-## Versioning
-
-v8r follows [semantic versioning](https://semver.org/). For this project, the "API" is defined as:
-
-- CLI flags and options
-- CLI exit codes
-- The configuration file format
-- The native JSON output format
-
-A "breaking change" also includes:
-
-- Dropping compatibility with a major Node JS version
-- Dropping compatibility with a JSON Schema draft
-
-## FAQ
-
-### ❓ How does `v8r` decide what schema to validate against if I don't supply one?
-
-💡 `v8r` queries the [Schema Store catalog](https://www.schemastore.org/) to try and find a suitable schema based on the name of the input file.
-
-### ❓ My file is valid, but it doesn't validate against one of the suggested schemas.
-
-💡 `v8r` is a fairly thin layer of glue between [Schema Store](https://www.schemastore.org/) (where the schemas come from) and [ajv](https://www.npmjs.com/package/ajv) (the validation engine). It is likely that this kind of problem is either an issue with the schema or validation engine.
-
-* Schema store issue tracker: https://github.com/SchemaStore/schemastore/issues
-* Ajv issue tracker: https://github.com/ajv-validator/ajv/issues
-
-### ❓ What JSON schema versions are compatible?
-
-💡 `v8r` works with JSON schema drafts:
-
-* draft-04
-* draft-06
-* draft-07
-* draft 2019-09
-* draft 2020-12
-
-### ❓ Will 100% of the schemas on schemastore.org work with this tool?
-
-💡 No. There are some with [known issues](https://github.com/chris48s/v8r/issues/18)
-
-### ❓ Can `v8r` validate against a local schema?
-
-💡 Yes. The `--schema` flag can be either a path to a local file or a URL. You can also use a [config file](#configuration) to include local schemas in a custom catalog.
+📚 Jump into the [Documentation](https://chris48s.github.io/v8r) to get started

package/config-schema.json

@@ -49,13 +49,8 @@
                 "type": "string"
               },
               "parser": {
-                "description": "A custom parser to use for files matching fileMatch instead of trying to infer the correct parser from the filename",
-                "type": "string",
-                "enum": [
-                  "json",
-                  "yaml",
-                  "json5"
-                ]
+                "description": "A custom parser to use for files matching fileMatch instead of trying to infer the correct parser from the filename. 'json', 'json5', 'toml' and 'yaml' are always valid. Plugins may define additional values which are valid here.",
+                "type": "string"
               }
             }
           }
@@ -63,12 +58,8 @@
       }
     },
     "format": {
-      "description": "Output format for validation results",
-      "type": "string",
-      "enum": [
-        "text",
-        "json"
-      ]
+      "description": "Output format for validation results. 'text' and 'json' are always valid. Plugins may define additional values which are valid here.",
+      "type": "string"
     },
     "ignoreErrors": {
       "description": "Exit with code 0 even if an error was encountered. True means a non-zero exit code is only issued if validation could be completed successfully and one or more files were invalid",
@@ -87,6 +78,15 @@
       "description": "Level of verbose logging. 0 is standard, higher numbers are more verbose",
       "type": "integer",
       "minimum": 0
+    },
+    "plugins": {
+      "type": "array",
+      "description": "An array of strings describing v8r plugins to load",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^(package:|file:)"
+      }
     }
   }
 }

package/package.json

@@ -1,20 +1,19 @@
 {
   "name": "v8r",
-  "version": "3.1.0",
-  "description": "A command-line JSON and YAML validator that's on your wavelength",
+  "version": "4.0.0",
+  "description": "A command-line JSON, YAML and TOML validator that's on your wavelength",
   "scripts": {
     "test": "V8R_CACHE_NAME=v8r-test c8 --reporter=text mocha \"src/**/*.spec.js\"",
-    "lint": "eslint \"**/*.{js,cjs}\"",
+    "lint": "eslint \"**/*.{js,cjs,mjs}\"",
     "coverage": "c8 report --reporter=cobertura",
-    "prettier": "prettier --write \"**/*.{js,cjs}\"",
-    "prettier:check": "prettier --check \"**/*.{js,cjs}\"",
+    "prettier": "prettier --write \"**/*.{js,cjs,mjs}\"",
+    "prettier:check": "prettier --check \"**/*.{js,cjs,mjs}\"",
     "v8r": "src/index.js"
   },
   "bin": {
     "v8r": "src/index.js"
   },
-  "main": "src/index.js",
-  "exports": "./src/index.js",
+  "exports": "./src/public.js",
   "files": [
     "src/**/!(*.spec).js",
     "config-schema.json",
@@ -46,15 +45,17 @@
     "yargs": "^17.0.1"
   },
   "devDependencies": {
-    "c8": "^9.1.0",
-    "eslint": "^9.2.0",
+    "c8": "^10.1.2",
+    "eslint": "^9.9.0",
     "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-jsdoc": "^50.2.2",
     "eslint-plugin-mocha": "^10.0.3",
     "eslint-plugin-prettier": "^5.0.0",
-    "mocha": "^10.0.0",
+    "mocha": "^10.7.3",
     "mock-cwd": "^1.0.0",
     "nock": "^13.0.4",
-    "prettier": "^3.0.0"
+    "prettier": "^3.0.0",
+    "prettier-plugin-jsdoc": "^1.3.0"
   },
   "engines": {
     "node": ">=18"

package/src/{config.js → bootstrap.js}

@@ -3,30 +3,19 @@ import { createRequire } from "module";
 // https://nodejs.org/api/esm.html#esm_experimental_json_modules
 const require = createRequire(import.meta.url);
 
-import Ajv2019 from "ajv/dist/2019.js";
 import { cosmiconfig } from "cosmiconfig";
 import decamelize from "decamelize";
 import isUrl from "is-url";
 import path from "path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
+import {
+  validateConfigAgainstSchema,
+  validateConfigDocumentParsers,
+  validateConfigOutputFormats,
+} from "./config-validators.js";
 import logger from "./logger.js";
-import { logErrors } from "./output-formatters.js";
-
-function validateConfig(configFile) {
-  const ajv = new Ajv2019({ allErrors: true, strict: false });
-  const schema = require("../config-schema.json");
-  const validateFn = ajv.compile(schema);
-  const valid = validateFn(configFile.config);
-  if (!valid) {
-    logErrors(
-      configFile.filepath ? configFile.filepath : "",
-      validateFn.errors,
-    );
-    throw new Error("Malformed config file");
-  }
-  return valid;
-}
+import { loadAllPlugins, resolveUserPlugins } from "./plugins.js";
 
 function preProcessConfig(configFile) {
   if (!configFile?.config?.customCatalog?.schemas) {
@@ -52,8 +41,6 @@ async function getCosmiConfig(cosmiconfigOptions) {
   } else {
     logger.info(`No config file found`);
   }
-  validateConfig(configFile);
-  preProcessConfig(configFile);
   return configFile;
 }
 
@@ -72,7 +59,7 @@ function getRelativeFilePath(config) {
   return path.relative(process.cwd(), config.filepath);
 }
 
-function parseArgs(argv, config) {
+function parseArgs(argv, config, documentFormats, outputFormats) {
   const parser = yargs(hideBin(argv));
 
   let command = "$0 <patterns..>";
@@ -91,7 +78,7 @@ function parseArgs(argv, config) {
   parser
     .command(
       command,
-      "Validate local json/yaml files against schema(s)",
+      `Validate local ${documentFormats.join("/")} files against schema(s)`,
       (yargs) => {
         yargs.positional("patterns", patternsOpts);
       },
@@ -142,7 +129,7 @@ function parseArgs(argv, config) {
     })
     .option("format", {
       type: "string",
-      choices: ["text", "json"],
+      choices: outputFormats,
       default: "text",
       describe: "Output format for validation results",
     })
@@ -168,10 +155,68 @@ function parseArgs(argv, config) {
   return parser.argv;
 }
 
-async function getConfig(argv, cosmiconfigOptions = {}) {
-  const config = await getCosmiConfig(cosmiconfigOptions);
-  const args = parseArgs(argv, config);
-  return mergeConfigs(args, config);
+function getDocumentFormats(loadedPlugins) {
+  let documentFormats = [];
+  for (const plugin of loadedPlugins) {
+    documentFormats = documentFormats.concat(plugin.registerInputFileParsers());
+  }
+  return documentFormats;
+}
+
+function getOutputFormats(loadedPlugins) {
+  let outputFormats = [];
+  for (const plugin of loadedPlugins) {
+    outputFormats = outputFormats.concat(plugin.registerOutputFormats());
+  }
+  return outputFormats;
+}
+
+async function bootstrap(argv, config, cosmiconfigOptions = {}) {
+  if (config) {
+    // special case for unit testing purposes
+    // this allows us to inject an incomplete config and bypass the validation
+    const { allLoadedPlugins, loadedCorePlugins, loadedUserPlugins } =
+      await loadAllPlugins(config.plugins || []);
+    return {
+      config,
+      allLoadedPlugins,
+      loadedCorePlugins,
+      loadedUserPlugins,
+    };
+  }
+
+  // load the config file and validate it against the schema
+  const configFile = await getCosmiConfig(cosmiconfigOptions);
+  validateConfigAgainstSchema(configFile);
+
+  // load both core and user plugins
+  let plugins = resolveUserPlugins(configFile.config.plugins || []);
+  const { allLoadedPlugins, loadedCorePlugins, loadedUserPlugins } =
+    await loadAllPlugins(plugins);
+  const documentFormats = getDocumentFormats(allLoadedPlugins);
+  const outputFormats = getOutputFormats(allLoadedPlugins);
+
+  // now we have documentFormats and outputFormats
+  // we can finish validating and processing the config
+  validateConfigDocumentParsers(configFile, documentFormats);
+  validateConfigOutputFormats(configFile, outputFormats);
+  preProcessConfig(configFile);
+
+  // parse command line arguments
+  const args = parseArgs(argv, configFile, documentFormats, outputFormats);
+
+  return {
+    config: mergeConfigs(args, configFile),
+    allLoadedPlugins,
+    loadedCorePlugins,
+    loadedUserPlugins,
+  };
 }
 
-export { getConfig, parseArgs, preProcessConfig, validateConfig };
+export {
+  bootstrap,
+  getDocumentFormats,
+  getOutputFormats,
+  parseArgs,
+  preProcessConfig,
+};

package/src/cli.js

@@ -4,19 +4,18 @@ import os from "os";
 import path from "path";
 import isUrl from "is-url";
 import { validate } from "./ajv.js";
+import { bootstrap } from "./bootstrap.js";
 import { Cache } from "./cache.js";
 import { getCatalogs, getMatchForFilename } from "./catalogs.js";
-import { getConfig } from "./config.js";
 import { getFiles } from "./glob.js";
 import { getFromUrlOrFile } from "./io.js";
 import logger from "./logger.js";
-import { logErrors, resultsToJson } from "./output-formatters.js";
-import { parseDocument } from "./parser.js";
+import { parseFile } from "./parser.js";
 
 const EXIT = {
   VALID: 0,
   ERROR: 1,
-  INVALID_CONFIG: 97,
+  INVALID_CONFIG_OR_PLUGIN: 97,
   NOT_FOUND: 98,
   INVALID: 99,
 };
@@ -34,7 +33,7 @@ function getFlatCache() {
   return flatCache.load("v8r", CACHE_DIR);
 }
 
-async function validateFile(filename, config, cache) {
+async function validateFile(filename, config, plugins, cache) {
   logger.info(`Processing ${filename}`);
   let result = {
     fileLocation: filename,
@@ -55,9 +54,11 @@ async function validateFile(filename, config, cache) {
       `Validating ${filename} against schema from ${schemaLocation} ...`,
     );
 
-    const data = parseDocument(
+    const data = parseFile(
+      plugins,
       await fs.promises.readFile(filename, "utf8"),
-      catalogMatch.parser ? `.${catalogMatch.parser}` : path.extname(filename),
+      filename,
+      catalogMatch.parser,
     );
 
     const strictMode = config.verbose >= 2 ? "log" : false;
@@ -101,7 +102,7 @@ function resultsToStatusCode(results, ignoreErrors) {
 }
 
 function Validator() {
-  return async function (config) {
+  return async function (config, plugins) {
     let filenames = [];
     for (const pattern of config.patterns) {
       const matches = await getFiles(pattern);
@@ -115,20 +116,32 @@ function Validator() {
     const ttl = secondsToMilliseconds(config.cacheTtl || 0);
     const cache = new Cache(getFlatCache(), ttl);
 
-    const results = Object.fromEntries(filenames.map((key) => [key, null]));
-    for (const [filename] of Object.entries(results)) {
-      results[filename] = await validateFile(filename, config, cache);
-
-      if (results[filename].valid === false && config.format === "text") {
-        logErrors(filename, results[filename].errors);
+    let results = [];
+    for (const filename of filenames) {
+      const result = await validateFile(filename, config, plugins, cache);
+      results.push(result);
+
+      for (const plugin of plugins) {
+        const message = plugin.getSingleResultLogMessage(
+          result,
+          filename,
+          config.format,
+        );
+        if (message != null) {
+          logger.log(message);
+          break;
+        }
       }
-      // else: silence is golden
 
       cache.resetCounters();
     }
 
-    if (config.format === "json") {
-      resultsToJson(results);
+    for (const plugin of plugins) {
+      const message = plugin.getAllResultsLogMessage(results, config.format);
+      if (message != null) {
+        logger.log(message);
+        break;
+      }
     }
 
     return resultsToStatusCode(results, config.ignoreErrors);
@@ -136,21 +149,41 @@ function Validator() {
 }
 
 async function cli(config) {
-  if (!config) {
-    try {
-      config = await getConfig(process.argv);
-    } catch (e) {
-      logger.error(e.message);
-      return EXIT.INVALID_CONFIG;
-    }
+  let allLoadedPlugins, loadedCorePlugins, loadedUserPlugins;
+  try {
+    ({ config, allLoadedPlugins, loadedCorePlugins, loadedUserPlugins } =
+      await bootstrap(process.argv, config));
+  } catch (e) {
+    logger.error(e.message);
+    return EXIT.INVALID_CONFIG_OR_PLUGIN;
   }
 
   logger.setVerbosity(config.verbose);
   logger.debug(`Merged args/config: ${JSON.stringify(config, null, 2)}`);
 
+  /*
+  Note there is a bit of a chicken and egg problem here.
+  We have to load the plugins before we can load the config
+  but this logger.debug() needs to happen AFTER we call logger.setVerbosity().
+  */
+  logger.debug(
+    `Loaded user plugins: ${JSON.stringify(
+      loadedUserPlugins.map((plugin) => plugin.constructor.name),
+      null,
+      2,
+    )}`,
+  );
+  logger.debug(
+    `Loaded core plugins: ${JSON.stringify(
+      loadedCorePlugins.map((plugin) => plugin.constructor.name),
+      null,
+      2,
+    )}`,
+  );
+
   try {
     const validate = new Validator();
-    return await validate(config);
+    return await validate(config, allLoadedPlugins);
   } catch (e) {
     logger.error(e.message);
     return EXIT.ERROR;

package/src/config-validators.js

@@ -0,0 +1,54 @@
+import { createRequire } from "module";
+// TODO: once JSON modules is stable these requires could become imports
+// https://nodejs.org/api/esm.html#esm_experimental_json_modules
+const require = createRequire(import.meta.url);
+
+import Ajv2019 from "ajv/dist/2019.js";
+import logger from "./logger.js";
+import { formatErrors } from "./output-formatters.js";
+
+function validateConfigAgainstSchema(configFile) {
+  const ajv = new Ajv2019({ allErrors: true, strict: false });
+  const schema = require("../config-schema.json");
+  const validateFn = ajv.compile(schema);
+  const valid = validateFn(configFile.config);
+  if (!valid) {
+    logger.log(
+      formatErrors(
+        configFile.filepath ? configFile.filepath : "",
+        validateFn.errors,
+      ),
+    );
+    throw new Error("Malformed config file");
+  }
+  return true;
+}
+
+function validateConfigDocumentParsers(configFile, documentFormats) {
+  for (const schema of configFile.config?.customCatalog?.schemas || []) {
+    if (schema?.parser != null && !documentFormats.includes(schema?.parser)) {
+      throw new Error(
+        `Malformed config file: "${schema.parser}" not in ${JSON.stringify(documentFormats)}`,
+      );
+    }
+  }
+  return true;
+}
+
+function validateConfigOutputFormats(configFile, outputFormats) {
+  if (
+    configFile.config?.format != null &&
+    !outputFormats.includes(configFile.config?.format)
+  ) {
+    throw new Error(
+      `Malformed config file: "${configFile.config.format}" not in ${JSON.stringify(outputFormats)}`,
+    );
+  }
+  return true;
+}
+
+export {
+  validateConfigAgainstSchema,
+  validateConfigDocumentParsers,
+  validateConfigOutputFormats,
+};

package/src/glob.js

@@ -3,7 +3,9 @@ import logger from "./logger.js";
 
 async function getFiles(pattern) {
   try {
-    return await glob(pattern, { dot: true, dotRelative: true });
+    let matches = await glob(pattern, { dot: true, dotRelative: true });
+    matches.sort((a, b) => a.localeCompare(b));
+    return matches;
   } catch (e) {
     logger.error(e.message);
     return [];

package/src/output-formatters.js

@@ -1,19 +1,13 @@
 import Ajv from "ajv";
-import logger from "./logger.js";
 
-function logErrors(filename, errors) {
+function formatErrors(filename, errors) {
   const ajv = new Ajv();
-  logger.log(
+  return (
     ajv.errorsText(errors, {
       separator: "\n",
       dataVar: filename + "#",
-    }),
+    }) + "\n"
   );
-  logger.log("");
 }
 
-function resultsToJson(results) {
-  logger.log(JSON.stringify({ results }, null, 2));
-}
-
-export { logErrors, resultsToJson };
+export { formatErrors };

package/src/parser.js

@@ -1,24 +1,24 @@
-import JSON5 from "json5";
+import path from "path";
 import yaml from "js-yaml";
-import { parse } from "smol-toml";
+import { Document } from "./plugins.js";
 
-function parseDocument(contents, format) {
-  switch (format) {
-    case ".json":
-    case ".geojson":
-    case ".jsonld":
-      return JSON.parse(contents);
-    case ".jsonc":
-    case ".json5":
-      return JSON5.parse(contents);
-    case ".yml":
-    case ".yaml":
-      return yaml.load(contents);
-    case ".toml":
-      return parse(contents);
-    default:
-      throw new Error(`Unsupported format ${format}`);
+function parseFile(plugins, contents, filename, parser) {
+  for (const plugin of plugins) {
+    const result = plugin.parseInputFile(contents, filename, parser);
+    if (result != null) {
+      if (!(result instanceof Document)) {
+        throw new Error(
+          `Plugin ${plugin.constructor.name} returned an unexpected type from parseInputFile hook. Expected Document, got ${typeof result}`,
+        );
+      }
+      return result.document;
+    }
   }
+
+  const errorMessage = parser
+    ? `Unsupported format ${parser}`
+    : `Unsupported format ${path.extname(filename).slice(1)}`;
+  throw new Error(errorMessage);
 }
 
 function parseSchema(contents, location) {
@@ -33,4 +33,4 @@ function parseSchema(contents, location) {
   return JSON.parse(contents);
 }
 
-export { parseDocument, parseSchema };
+export { parseFile, parseSchema };

package/src/plugins/output-json.js

@@ -0,0 +1,17 @@
+import { BasePlugin } from "../plugins.js";
+
+class JsonOutput extends BasePlugin {
+  static name = "v8r-plugin-json-output";
+
+  registerOutputFormats() {
+    return ["json"];
+  }
+
+  getAllResultsLogMessage(results, format) {
+    if (format === "json") {
+      return JSON.stringify({ results }, null, 2);
+    }
+  }
+}
+
+export default JsonOutput;

package/src/plugins/output-text.js

@@ -0,0 +1,18 @@
+import { BasePlugin } from "../plugins.js";
+import { formatErrors } from "../output-formatters.js";
+
+class TextOutput extends BasePlugin {
+  static name = "v8r-plugin-text-output";
+
+  registerOutputFormats() {
+    return ["text"];
+  }
+
+  getSingleResultLogMessage(result, fileLocation, format) {
+    if (result.valid === false && format === "text") {
+      return formatErrors(fileLocation, result.errors);
+    }
+  }
+}
+
+export default TextOutput;

package/src/plugins/parser-json.js

@@ -0,0 +1,25 @@
+import { BasePlugin, Document } from "../plugins.js";
+
+class JsonParser extends BasePlugin {
+  static name = "v8r-plugin-json-parser";
+
+  registerInputFileParsers() {
+    return ["json"];
+  }
+
+  parseInputFile(contents, fileLocation, parser) {
+    if (parser === "json") {
+      return new Document(JSON.parse(contents));
+    } else if (parser == null) {
+      if (
+        fileLocation.endsWith(".json") ||
+        fileLocation.endsWith(".geojson") ||
+        fileLocation.endsWith(".jsonld")
+      ) {
+        return new Document(JSON.parse(contents));
+      }
+    }
+  }
+}
+
+export default JsonParser;

package/src/plugins/parser-json5.js

@@ -0,0 +1,22 @@
+import JSON5 from "json5";
+import { BasePlugin, Document } from "../plugins.js";
+
+class Json5Parser extends BasePlugin {
+  static name = "v8r-plugin-json5-parser";
+
+  registerInputFileParsers() {
+    return ["json5"];
+  }
+
+  parseInputFile(contents, fileLocation, parser) {
+    if (parser === "json5") {
+      return new Document(JSON5.parse(contents));
+    } else if (parser == null) {
+      if (fileLocation.endsWith(".json5") || fileLocation.endsWith(".jsonc")) {
+        return new Document(JSON5.parse(contents));
+      }
+    }
+  }
+}
+
+export default Json5Parser;

package/src/plugins/parser-toml.js

@@ -0,0 +1,22 @@
+import { parse } from "smol-toml";
+import { BasePlugin, Document } from "../plugins.js";
+
+class TomlParser extends BasePlugin {
+  static name = "v8r-plugin-toml-parser";
+
+  registerInputFileParsers() {
+    return ["toml"];
+  }
+
+  parseInputFile(contents, fileLocation, parser) {
+    if (parser === "toml") {
+      return new Document(parse(contents));
+    } else if (parser == null) {
+      if (fileLocation.endsWith(".toml")) {
+        return new Document(parse(contents));
+      }
+    }
+  }
+}
+
+export default TomlParser;

package/src/plugins/parser-yaml.js

@@ -0,0 +1,22 @@
+import yaml from "js-yaml";
+import { BasePlugin, Document } from "../plugins.js";
+
+class YamlParser extends BasePlugin {
+  static name = "v8r-plugin-yaml-parser";
+
+  registerInputFileParsers() {
+    return ["yaml"];
+  }
+
+  parseInputFile(contents, fileLocation, parser) {
+    if (parser === "yaml") {
+      return new Document(yaml.load(contents));
+    } else if (parser == null) {
+      if (fileLocation.endsWith(".yaml") || fileLocation.endsWith(".yml")) {
+        return new Document(yaml.load(contents));
+      }
+    }
+  }
+}
+
+export default YamlParser;

package/src/plugins.js

@@ -0,0 +1,223 @@
+import path from "path";
+
+/**
+ * Base class for all v8r plugins.
+ *
+ * @abstract
+ */
+class BasePlugin {
+  /**
+   * Name of the plugin. All plugins must declare a name starting with
+   * `v8r-plugin-`.
+   *
+   * @type {string}
+   * @static
+   */
+  static name = "untitled plugin";
+
+  /**
+   * Use the `registerInputFileParsers` hook to tell v8r about additional file
+   * formats that can be parsed. Any parsers registered with this hook become
+   * valid values for the `parser` property in custom schemas.
+   *
+   * @returns {string[]} File parsers to register
+   */
+  registerInputFileParsers() {
+    return [];
+  }
+
+  /**
+   * Use the `parseInputFile` hook to tell v8r how to parse files.
+   *
+   * If `parseInputFile` returns anything other than undefined, that return
+   * value will be used and no further plugins will be invoked. If
+   * `parseInputFile` returns undefined, v8r will move on to the next plugin in
+   * the stack.
+   *
+   * @param {string} contents - The unparsed file content.
+   * @param {string} fileLocation - The file path. Filenames are resolved and
+   *   normalised by [glob](https://www.npmjs.com/package/glob) using the
+   *   `dotRelative` option. This means relative paths in the current directory
+   *   will be prefixed with `./` (or `.\` on Windows) even if this was not
+   *   present in the input filename or pattern.
+   * @param {string | undefined} parser - If the user has specified a parser to
+   *   use for this file in a custom schema, this will be passed to
+   *   `parseInputFile` in the `parser` param.
+   * @returns {Document | undefined} Parsed file contents
+   */
+  // eslint-disable-next-line no-unused-vars
+  parseInputFile(contents, fileLocation, parser) {
+    return undefined;
+  }
+
+  /**
+   * Use the `registerOutputFormats` hook to tell v8r about additional output
+   * formats that can be generated. Any formats registered with this hook become
+   * valid values for the `format` property in the config file and the
+   * `--format` command line argument.
+   *
+   * @returns {string[]} Output formats to register
+   */
+  registerOutputFormats() {
+    return [];
+  }
+
+  /**
+   * Use the `getSingleResultLogMessage` hook to provide a log message for v8r
+   * to output after processing a single file.
+   *
+   * If `getSingleResultLogMessage` returns anything other than undefined, that
+   * return value will be used and no further plugins will be invoked. If
+   * `getSingleResultLogMessage` returns undefined, v8r will move on to the next
+   * plugin in the stack.
+   *
+   * Any message returned from this function will be written to stdout.
+   *
+   * @param {ValidationResult} result - Result of attempting to validate this
+   *   document.
+   * @param {string} fileLocation - The document file path. Filenames are
+   *   resolved and normalised by [glob](https://www.npmjs.com/package/glob)
+   *   using the `dotRelative` option. This means relative paths in the current
+   *   directory will be prefixed with `./` (or `.\` on Windows) even if this
+   *   was not present in the input filename or pattern.
+   * @param {string} format - The user's requested output format as specified in
+   *   the config file or via the `--format` command line argument.
+   * @returns {string | undefined} Log message
+   */
+  // eslint-disable-next-line no-unused-vars
+  getSingleResultLogMessage(result, fileLocation, format) {
+    return undefined;
+  }
+
+  /**
+   * Use the `getAllResultsLogMessage` hook to provide a log message for v8r to
+   * output after processing all files.
+   *
+   * If `getAllResultsLogMessage` returns anything other than undefined, that
+   * return value will be used and no further plugins will be invoked. If
+   * `getAllResultsLogMessage` returns undefined, v8r will move on to the next
+   * plugin in the stack.
+   *
+   * Any message returned from this function will be written to stdout.
+   *
+   * @param {ValidationResult[]} results - Results of attempting to validate
+   *   these documents.
+   * @param {string} format - The user's requested output format as specified in
+   *   the config file or via the `--format` command line argument.
+   * @returns {string | undefined} Log message
+   */
+  // eslint-disable-next-line no-unused-vars
+  getAllResultsLogMessage(results, format) {
+    return undefined;
+  }
+}
+
+class Document {
+  /**
+   * Document is a thin wrapper class for a document we want to validate after
+   * parsing a file
+   *
+   * @param {any} document - The object to be wrapped
+   */
+  constructor(document) {
+    this.document = document;
+  }
+}
+
+function validatePlugin(plugin) {
+  if (
+    typeof plugin.name !== "string" ||
+    !plugin.name.startsWith("v8r-plugin-")
+  ) {
+    throw new Error(`Plugin ${plugin.name} does not declare a valid name`);
+  }
+
+  if (!(plugin.prototype instanceof BasePlugin)) {
+    throw new Error(`Plugin ${plugin.name} does not extend BasePlugin`);
+  }
+
+  for (const prop of Object.getOwnPropertyNames(BasePlugin.prototype)) {
+    const method = plugin.prototype[prop];
+    const argCount = plugin.prototype[prop].length;
+    if (typeof method !== "function") {
+      throw new Error(
+        `Error loading plugin ${plugin.name}: must have a method called ${method}`,
+      );
+    }
+    const expectedArgs = BasePlugin.prototype[prop].length;
+    if (expectedArgs !== argCount) {
+      throw new Error(
+        `Error loading plugin ${plugin.name}: ${prop} must take exactly ${expectedArgs} arguments`,
+      );
+    }
+  }
+}
+
+function resolveUserPlugins(userPlugins) {
+  let plugins = [];
+  for (let plugin of userPlugins) {
+    if (plugin.startsWith("package:")) {
+      plugins.push(plugin.slice(8));
+    }
+    if (plugin.startsWith("file:")) {
+      plugins.push(path.resolve(process.cwd(), plugin.slice(5)));
+    }
+  }
+  return plugins;
+}
+
+async function loadPlugins(plugins) {
+  let loadedPlugins = [];
+  for (const plugin of plugins) {
+    loadedPlugins.push(await import(plugin));
+  }
+  loadedPlugins = loadedPlugins.map((plugin) => plugin.default);
+  loadedPlugins.forEach((plugin) => validatePlugin(plugin));
+  loadedPlugins = loadedPlugins.map((plugin) => new plugin());
+  return loadedPlugins;
+}
+
+async function loadAllPlugins(userPlugins) {
+  const loadedUserPlugins = await loadPlugins(userPlugins);
+
+  const corePlugins = [
+    "./plugins/parser-json.js",
+    "./plugins/parser-json5.js",
+    "./plugins/parser-toml.js",
+    "./plugins/parser-yaml.js",
+    "./plugins/output-text.js",
+    "./plugins/output-json.js",
+  ];
+  const loadedCorePlugins = await loadPlugins(corePlugins);
+
+  return {
+    allLoadedPlugins: loadedUserPlugins.concat(loadedCorePlugins),
+    loadedCorePlugins,
+    loadedUserPlugins,
+  };
+}
+
+/**
+ * @typedef {object} ValidationResult
+ * @property {string} fileLocation - Path of the document that was validated.
+ *   Filenames are resolved and normalised by
+ *   [glob](https://www.npmjs.com/package/glob) using the `dotRelative` option.
+ *   This means relative paths in the current directory will be prefixed with
+ *   `./` (or `.\` on Windows) even if this was not present in the input
+ *   filename or pattern.
+ * @property {string | null} schemaLocation - Location of the schema used to
+ *   validate this file if one could be found. `null` if no schema was found.
+ * @property {boolean | null} valid - Result of the validation (true/false) if a
+ *   schema was found. `null` if no schema was found and no validation could be
+ *   performed.
+ * @property {ErrorObject[]} errors - An array of [AJV Error
+ *   Objects](https://ajv.js.org/api.html#error-objects) describing any errors
+ *   encountered when validating this document.
+ */
+
+/**
+ * @external ErrorObject
+ * @see https://ajv.js.org/api.html#error-objects
+ */
+
+export { BasePlugin, Document, loadAllPlugins, resolveUserPlugins };

package/src/public.js

@@ -0,0 +1,3 @@
+import { BasePlugin, Document } from "./plugins.js";
+
+export { BasePlugin, Document };