v8r/src/plugins.js

A command-line JSON, YAML and TOML validator that's on your wavelength

/**
 * 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. The result of successfully parsing a file can either be a single
   * Document object or an array of Document objects.
   *
   * @param {string} contents - The unparsed file content.
   * @param {string} fileLocation - The file path.
   * @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 | 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 `outputFormat` property in the config file and the
   * `--output-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} format - The user's requested output format as specified in
   *   the config file or via the `--output-format` command line argument.
   * @returns {string | undefined} Log message
   */
  // eslint-disable-next-line no-unused-vars
  getSingleResultLogMessage(result, 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 `--output-format` command line argument.
   * @returns {string | undefined} Log message
   */
  // eslint-disable-next-line no-unused-vars
  getAllResultsLogMessage(results, format) {
    return undefined;
  }
}

class Document {
  /* eslint-disable jsdoc/reject-any-type */
  /**
   * 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
   */
  /* eslint-enable jsdoc/reject-any-type */
  constructor(document) {
    this.document = document;
  }
}

/**
 * @typedef {object} ValidationResult
 * @property {string} fileLocation - Path of the document that was validated.
 * @property {number | null} documentIndex - Some file formats allow multiple
 *   documents to be embedded in one file (e.g:
 *   [yaml](https://www.yaml.info/learn/document.html)). In these cases,
 *   `documentIndex` identifies is used to identify the sub document within the
 *   file. `documentIndex` will be `null` when there is a one-to-one
 *   relationship between file and document.
 * @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 };