v8r 4.2.1 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 📦 [4.4.0](https://www.npmjs.com/package/v8r/v/4.4.0) - 2025-04-26
+
+Version 4.4.0 is a deprecation release. This release adds deprecation warnings for
+upcoming breaking changes that will be made in version 5.0
+
+* This release adds the `--output-format` CLI argument and `outputFormat` config file key.
+  In v8r 4.4.0 `--format` and `format` can still be used as aliases.
+  In version 5 `--format` and `format` will be removed.
+  It is recommended to switch to using `--output-format` and `outputFormat` now.
+* Starting from v8r version 5, v8r will ignore patterns in `.gitignore` by default.
+* In v8r version 5 the `fileLocation` argument of `getSingleResultLogMessage` will be removed.
+  The signature will become `getSingleResultLogMessage(result, format)`.
+  Plugins implementing the `getSingleResultLogMessage` plugin hook will need to to update
+  the signature to be compatible with version 5.
+  If you are using `fileLocation` in the `getSingleResultLogMessage` function body,
+  switch to using `result.fileLocation`.
+* Starting from v8r version 5 file paths will no longer be passed to plugins in dot-relative notation.
+  Plugins implementing the `getSingleResultLogMessage`, `getAllResultsLogMessage` and `parseInputFile`
+  plugin hooks may need to be updated.
+
+## 📦 [4.3.0](https://www.npmjs.com/package/v8r/v/4.3.0) - 2025-04-21
+
+* Add ignore patern files. v8r now looks for ignore patterns in `.v8rignore` by default.
+  More info: https://chris48s.github.io/v8r/ignoring-files/
+* Include the prop name in `additionalProperty` log message.
+* Allow config file to contain `$schema` key.
+* Fix: Clear the cache on init if TTL is 0.
+
 ## 📦 [4.2.1](https://www.npmjs.com/package/v8r/v/4.2.1) - 2024-12-14
 
 * Upgrade to flat-cache 6.

package/config-schema.json

@@ -3,6 +3,13 @@
   "$schema": "https://json-schema.org/draft/2019-09/schema",
   "type": "object",
   "additionalProperties": false,
+  "allOf": [
+    {
+      "not": {
+        "required": ["format", "outputFormat"]
+      }
+    }
+  ],
   "properties": {
     "cacheTtl": {
       "description": "Remove cached HTTP responses older than cacheTtl seconds old. Specifying 0 clears and disables cache completely",
@@ -57,14 +64,27 @@
         }
       }
     },
-    "format": {
+    "outputFormat": {
       "description": "Output format for validation results. 'text' and 'json' are always valid. Plugins may define additional values which are valid here.",
       "type": "string"
     },
+    "format": {
+      "description": "Output format for validation results. 'text' and 'json' are always valid. Plugins may define additional values which are valid here.",
+      "type": "string",
+      "deprecated": true
+    },
     "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",
       "type": "boolean"
     },
+    "ignorePatternFiles": {
+      "description": "A list of files containing glob patterns to ignore",
+      "uniqueItems": true,
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
     "patterns": {
       "type": "array",
       "description": "One or more filenames or glob patterns describing local file or files to validate",
@@ -87,6 +107,9 @@
         "type": "string",
         "pattern": "^(package:|file:)"
       }
+    },
+    "$schema": {
+      "type": "string"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v8r",
-  "version": "4.2.1",
+  "version": "4.4.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\"",
@@ -37,6 +37,7 @@
     "glob": "^10.1.0",
     "global-agent": "^3.0.0",
     "got": "^13.0.0",
+    "ignore": "^7.0.0",
     "is-url": "^1.2.4",
     "js-yaml": "^4.0.0",
     "json5": "^2.2.0",
@@ -47,13 +48,13 @@
   "devDependencies": {
     "c8": "^10.1.2",
     "eslint": "^9.9.0",
-    "eslint-config-prettier": "^9.0.0",
+    "eslint-config-prettier": "^10.1.2",
     "eslint-plugin-jsdoc": "^50.2.2",
     "eslint-plugin-mocha": "^10.0.3",
     "eslint-plugin-prettier": "^5.0.0",
     "mocha": "^11.0.1",
     "mock-cwd": "^1.0.0",
-    "nock": "^13.0.4",
+    "nock": "^14.0.4",
     "prettier": "^3.0.0",
     "prettier-plugin-jsdoc": "^1.3.0"
   },

package/src/bootstrap.js

@@ -53,6 +53,8 @@ function mergeConfigs(args, config) {
   if (config.filepath) {
     mergedConfig.configFileRelativePath = getRelativeFilePath(config);
   }
+  // https://github.com/chris48s/v8r/issues/494
+  delete mergedConfig.format;
   return mergedConfig;
 }
 
@@ -76,13 +78,58 @@ function parseArgs(argv, config, documentFormats, outputFormats) {
     )} (from config file ${getRelativeFilePath(config)})`;
   }
 
+  const ignoreFilesOpts = {
+    describe: "A list of files containing glob patterns to ignore",
+  };
+  let ignoreFilesDefault = [".v8rignore"];
+  ignoreFilesOpts.defaultDescription = `${JSON.stringify(ignoreFilesDefault)}`;
+  if (Object.keys(config.config).includes("ignorePatternFiles")) {
+    ignoreFilesDefault = config.config.ignorePatternFiles;
+    ignoreFilesOpts.defaultDescription = `${JSON.stringify(
+      ignoreFilesDefault,
+    )} (from config file ${getRelativeFilePath(config)})`;
+  }
+
   parser
     .command(
+      // command
       command,
+
+      // description
       `Validate local ${documentFormats.join("/")} files against schema(s)`,
+
+      // builder
       (yargs) => {
         yargs.positional("patterns", patternsOpts);
       },
+
+      // handler
+      (args) => {
+        /*
+        Yargs doesn't allow .conflicts() with an argument that has a default
+        value (it considers the arg "set" even if we just use the default)
+        so we need to apply the default values here.
+        */
+        if (args.ignorePatternFiles === undefined) {
+          args.ignorePatternFiles = args["ignore-pattern-files"] =
+            ignoreFilesDefault;
+        }
+
+        if (args.ignore === false) {
+          args.ignorePatternFiles = args["ignore-pattern-files"] = [];
+        }
+
+        if (args.ignore === undefined) {
+          args.ignore = true;
+        }
+
+        // https://github.com/chris48s/v8r/issues/494
+        if (process.argv.includes("--format")) {
+          logger.warning(
+            "In v8r version 5 the --format argument will be removed. Switch to using --output-format",
+          );
+        }
+      },
     )
     .version(
       // Workaround for https://github.com/yargs/yargs/issues/1934
@@ -110,7 +157,7 @@ function parseArgs(argv, config, documentFormats, outputFormats) {
       alias: "c",
       array: true,
       describe:
-        "Local path or URL of custom catalogs to use prior to schemastore.org",
+        "A list of local paths or URLs of custom catalogs to use prior to schemastore.org",
     })
     .conflicts("schema", "catalogs")
     .option("ignore-errors", {
@@ -121,6 +168,17 @@ function parseArgs(argv, config, documentFormats, outputFormats) {
         "means a non-zero exit code is only issued if validation could be " +
         "completed successfully and one or more files were invalid",
     })
+    .option("ignore-pattern-files", {
+      type: "string",
+      array: true,
+      describe: "A list of files containing glob patterns to ignore",
+      ...ignoreFilesOpts,
+    })
+    .option("no-ignore", {
+      type: "boolean",
+      describe: "Disable all ignore files",
+    })
+    .conflicts("ignore-pattern-files", "no-ignore")
     .option("cache-ttl", {
       type: "number",
       default: 600,
@@ -128,11 +186,14 @@ function parseArgs(argv, config, documentFormats, outputFormats) {
         "Remove cached HTTP responses older than <cache-ttl> seconds old. " +
         "Passing 0 clears and disables cache completely",
     })
-    .option("format", {
+    .option("output-format", {
       type: "string",
       choices: outputFormats,
       default: "text",
-      describe: "Output format for validation results",
+      // https://github.com/chris48s/v8r/issues/494
+      describe:
+        "Output format for validation results. The '--format' alias is deprecated.",
+      alias: "format",
     })
     .example([
       ["$0 file.json", "Validate a single file"],
@@ -144,7 +205,7 @@ function parseArgs(argv, config, documentFormats, outputFormats) {
     ]);
 
   for (const [key, value] of Object.entries(config.config)) {
-    if (["cacheTtl", "format", "ignoreErrors", "verbose"].includes(key)) {
+    if (["cacheTtl", "outputFormat", "ignoreErrors", "verbose"].includes(key)) {
       parser.default(
         decamelize(key, { separator: "-" }),
         value,
@@ -190,6 +251,14 @@ async function bootstrap(argv, config, cosmiconfigOptions = {}) {
   const configFile = await getCosmiConfig(cosmiconfigOptions);
   validateConfigAgainstSchema(configFile);
 
+  // https://github.com/chris48s/v8r/issues/494
+  if (configFile.config.format) {
+    logger.warning(
+      "In v8r version 5 the 'format' config file key will be removed. Switch to using 'outputFormat'",
+    );
+    configFile.config.outputFormat = configFile.config.format;
+  }
+
   // load both core and user plugins
   let plugins = resolveUserPlugins(configFile.config.plugins || []);
   const { allLoadedPlugins, loadedCorePlugins, loadedUserPlugins } =
@@ -205,6 +274,11 @@ async function bootstrap(argv, config, cosmiconfigOptions = {}) {
   // parse command line arguments
   const args = parseArgs(argv, configFile, documentFormats, outputFormats);
 
+  // https://github.com/chris48s/v8r/issues/599
+  logger.warning(
+    "Starting from v8r version 5, v8r will ignore patterns in .gitignore by default.",
+  );
+
   return {
     config: mergeConfigs(args, configFile),
     allLoadedPlugins,

package/src/cache.js

@@ -8,6 +8,9 @@ class Cache {
     this.ttl = this.cache._cache.ttl || 0;
     this.callCounter = {};
     this.callLimit = 10;
+    if (this.ttl === 0) {
+      this.cache.clear();
+    }
   }
 
   limitDepth(url) {

package/src/cli.js

@@ -7,7 +7,7 @@ import { validate } from "./ajv.js";
 import { bootstrap } from "./bootstrap.js";
 import { Cache } from "./cache.js";
 import { getCatalogs, getMatchForFilename } from "./catalogs.js";
-import { getFiles } from "./glob.js";
+import { getFiles, NotFound } from "./glob.js";
 import { getFromUrlOrFile } from "./io.js";
 import logger from "./logger.js";
 import { getDocumentLocation } from "./output-formatters.js";
@@ -145,7 +145,7 @@ async function validateFile(filename, config, plugins, cache) {
       const message = plugin.getSingleResultLogMessage(
         result,
         filename,
-        config.format,
+        config.outputFormat,
       );
       if (message != null) {
         logger.log(message);
@@ -170,19 +170,16 @@ function resultsToStatusCode(results, ignoreErrors) {
 function Validator() {
   return async function (config, plugins) {
     let filenames = [];
-    for (const pattern of config.patterns) {
-      const matches = await getFiles(pattern);
-      if (matches.length === 0) {
-        logger.error(`Pattern '${pattern}' did not match any files`);
+    try {
+      filenames = await getFiles(config.patterns, config.ignorePatternFiles);
+    } catch (e) {
+      if (e instanceof NotFound) {
+        logger.error(e.message);
         return EXIT.NOT_FOUND;
       }
-      filenames = filenames.concat(matches);
+      throw e;
     }
 
-    // de-dupe and sort
-    filenames = [...new Set(filenames)];
-    filenames.sort((a, b) => a.localeCompare(b));
-
     const ttl = secondsToMilliseconds(config.cacheTtl || 0);
     const cache = new Cache(getFlatCache(ttl));
 
@@ -194,7 +191,10 @@ function Validator() {
     }
 
     for (const plugin of plugins) {
-      const message = plugin.getAllResultsLogMessage(results, config.format);
+      const message = plugin.getAllResultsLogMessage(
+        results,
+        config.outputFormat,
+      );
       if (message != null) {
         logger.log(message);
         break;

package/src/glob.js

@@ -1,13 +1,90 @@
+import fs from "node:fs";
+import path from "node:path";
 import { glob } from "glob";
+import ignore from "ignore";
 import logger from "./logger.js";
 
-async function getFiles(pattern) {
+class NotFound extends Error {}
+
+async function getMatches(pattern) {
   try {
-    return await glob(pattern, { dot: true, dotRelative: true });
+    return await glob(pattern, { dot: true });
   } catch (e) {
     logger.error(e.message);
     return [];
   }
 }
 
-export { getFiles };
+async function exists(path) {
+  try {
+    await fs.promises.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function filterIgnores(filenames, ignorePatterns) {
+  const ig = ignore();
+  for (const patterns of ignorePatterns) {
+    ig.add(patterns);
+  }
+  return ig.filter(filenames);
+}
+
+async function readIgnoreFiles(filenames) {
+  let content = [];
+  for (const filename of filenames) {
+    const abspath = path.join(process.cwd(), filename);
+    if (await exists(abspath)) {
+      content.push(await fs.promises.readFile(abspath, "utf8"));
+    }
+  }
+  return content;
+}
+
+function getSeparator() {
+  return process.platform == "win32" ? "\\" : "/";
+}
+
+async function getFiles(patterns, ignorePatternFiles) {
+  let filenames = [];
+
+  // find all the files matching input globs
+  for (const pattern of patterns) {
+    const matches = await getMatches(pattern);
+    if (matches.length === 0) {
+      throw new NotFound(`Pattern '${pattern}' did not match any files`);
+    }
+    filenames = filenames.concat(matches);
+  }
+
+  // de-dupe
+  filenames = [...new Set(filenames)];
+
+  // process ignores
+  const ignorePatterns = await readIgnoreFiles(ignorePatternFiles);
+  let filteredFilenames = await filterIgnores(filenames, ignorePatterns);
+
+  const diff = filenames.filter((x) => filteredFilenames.indexOf(x) < 0);
+  if (diff.length > 0) {
+    logger.debug(
+      `Ignoring file(s):\n    ${diff.join("\n    ")}\nbased on ignore patterns in\n    ${ignorePatternFiles.join("\n    ")}`,
+    );
+  }
+
+  // finally, sort
+  filteredFilenames.sort((a, b) => a.localeCompare(b));
+
+  if (filteredFilenames.length === 0) {
+    throw new NotFound(`Could not find any files to validate`);
+  }
+
+  const sep = getSeparator();
+  filteredFilenames = filteredFilenames.map((fn) =>
+    !fn.startsWith(".." + sep) ? "." + sep + fn : fn,
+  );
+  return filteredFilenames;
+}
+
+export { getFiles, NotFound };

package/src/logger.js

@@ -47,6 +47,12 @@ class Logger {
     this.writeErr(formatedMessage);
   }
 
+  warning(message) {
+    const formatedMessage = chalk.yellow.bold("▲ ") + message;
+    this.stderr.push(formatedMessage);
+    this.writeErr(formatedMessage);
+  }
+
   error(message) {
     const formatedMessage = chalk.red.bold("✖ ") + message;
     this.stderr.push(formatedMessage);

package/src/output-formatters.js

@@ -9,8 +9,25 @@ function getDocumentLocation(result) {
 
 function formatErrors(location, errors) {
   const ajv = new Ajv();
+  let formattedErrors = [];
+
+  if (errors) {
+    formattedErrors = errors.map(function (error) {
+      if (
+        error.keyword === "additionalProperties" &&
+        typeof error.params.additionalProperty === "string"
+      ) {
+        return {
+          ...error,
+          message: `${error.message}, found additional property '${error.params.additionalProperty}'`,
+        };
+      }
+      return error;
+    });
+  }
+
   return (
-    ajv.errorsText(errors, {
+    ajv.errorsText(formattedErrors, {
       separator: "\n",
       dataVar: location + "#",
     }) + "\n"

package/src/plugins.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import logger from "./logger.js";
 
 /**
  * Base class for all v8r plugins.
@@ -37,10 +38,9 @@ class BasePlugin {
    *
    * @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.
+   *   normalised using dot-relative notation. 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.
@@ -54,8 +54,8 @@ class BasePlugin {
   /**
    * 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.
+   * valid values for the `outputFormat` property in the config file and the
+   * `--output-format` command line argument.
    *
    * @returns {string[]} Output formats to register
    */
@@ -77,12 +77,11 @@ class BasePlugin {
    * @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.
+   *   resolved and normalised using dot-relative notation. 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.
+   *   the config file or via the `--output-format` command line argument.
    * @returns {string | undefined} Log message
    */
   // eslint-disable-next-line no-unused-vars
@@ -104,7 +103,7 @@ class BasePlugin {
    * @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.
+   *   the config file or via the `--output-format` command line argument.
    * @returns {string | undefined} Log message
    */
   // eslint-disable-next-line no-unused-vars
@@ -125,7 +124,11 @@ class Document {
   }
 }
 
-function validatePlugin(plugin) {
+function hasProperty(plugin, prop) {
+  return Object.prototype.hasOwnProperty.call(plugin.prototype, prop);
+}
+
+function validatePlugin(plugin, warnings) {
   if (
     typeof plugin.name !== "string" ||
     !plugin.name.startsWith("v8r-plugin-")
@@ -152,6 +155,29 @@ function validatePlugin(plugin) {
       );
     }
   }
+
+  if (warnings === true) {
+    // https://github.com/chris48s/v8r/issues/500
+    if (hasProperty(plugin, "getSingleResultLogMessage")) {
+      logger.warning(
+        "In v8r version 5 the fileLocation argument of getSingleResultLogMessage will be removed.\n" +
+          "  The signature will become getSingleResultLogMessage(result, format).\n" +
+          `  ${plugin.name} will need to be updated`,
+      );
+    }
+
+    // https://github.com/chris48s/v8r/issues/600
+    if (
+      hasProperty(plugin, "getSingleResultLogMessage") ||
+      hasProperty(plugin, "getAllResultsLogMessage") ||
+      hasProperty(plugin, "parseInputFile")
+    ) {
+      logger.warning(
+        "Starting from v8r version 5 file paths will no longer be passed to plugins in dot-relative notation.\n" +
+          `  ${plugin.name} may need to be updated`,
+      );
+    }
+  }
 }
 
 function resolveUserPlugins(userPlugins) {
@@ -167,19 +193,19 @@ function resolveUserPlugins(userPlugins) {
   return plugins;
 }
 
-async function loadPlugins(plugins) {
+async function loadPlugins(plugins, warnings) {
   let loadedPlugins = [];
   for (const plugin of plugins) {
     loadedPlugins.push(await import(plugin));
   }
   loadedPlugins = loadedPlugins.map((plugin) => plugin.default);
-  loadedPlugins.forEach((plugin) => validatePlugin(plugin));
+  loadedPlugins.forEach((plugin) => validatePlugin(plugin, warnings));
   loadedPlugins = loadedPlugins.map((plugin) => new plugin());
   return loadedPlugins;
 }
 
 async function loadAllPlugins(userPlugins) {
-  const loadedUserPlugins = await loadPlugins(userPlugins);
+  const loadedUserPlugins = await loadPlugins(userPlugins, true);
 
   const corePlugins = [
     "./plugins/parser-json.js",
@@ -189,7 +215,7 @@ async function loadAllPlugins(userPlugins) {
     "./plugins/output-text.js",
     "./plugins/output-json.js",
   ];
-  const loadedCorePlugins = await loadPlugins(corePlugins);
+  const loadedCorePlugins = await loadPlugins(corePlugins, false);
 
   return {
     allLoadedPlugins: loadedUserPlugins.concat(loadedCorePlugins),
@@ -201,11 +227,10 @@ async function loadAllPlugins(userPlugins) {
 /**
  * @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.
+ *   Filenames are resolved and normalised using dot-relative notation. 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 {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,