v8r 4.4.0 → 5.1.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 📦 [5.1.0](https://www.npmjs.com/package/v8r/v/5.1.0) - 2025-07-20
+
+* v8r now pre-warms the cache and fetches schemas in parallel.
+  This will improve decrease total run time for any run that involves fetching
+  more than one remote schema, or involves a schema with remote `$ref`s.
+* Improve handling of empty yaml files.
+
+## 📦 [5.0.0](https://www.npmjs.com/package/v8r/v/5.0.0) - 2025-05-10
+
+Following on from the deprecations in version 4.4.0,
+version 5.0.0 contains a number of breaking changes:
+
+* The `--format` CLI argument and `format` config file key have been removed.
+  Switch to using `--output-format` and `outputFormat`.
+* v8r now ignores patterns in `.gitignore` by default.
+* The `fileLocation` argument of `getSingleResultLogMessage` has been removed.
+  The signature is now `getSingleResultLogMessage(result, format)`.
+  Plugins implementing the `getSingleResultLogMessage` hook will need to to update
+  the signature.
+  If you are using `fileLocation` in the `getSingleResultLogMessage` function body,
+  switch to using `result.fileLocation`.
+* File paths are no longer passed to plugins in dot-relative notation.
+  Plugins implementing the `getSingleResultLogMessage`, `getAllResultsLogMessage` and `parseInputFile`
+  plugin hooks may need to be updated.
+* The minimum compatible node version is now Node 20.
+
+Other changes in this release:
+
+* v8r is now tested on node 24
+* Upgrade to latest major versions of core packages (got, glob, minimatch, etc)
+
 ## 📦 [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

package/config-schema.json

@@ -3,13 +3,6 @@
   "$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",
@@ -68,11 +61,6 @@
       "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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v8r",
-  "version": "4.4.0",
+  "version": "5.1.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\"",
@@ -34,23 +34,25 @@
     "cosmiconfig": "^9.0.0",
     "decamelize": "^6.0.0",
     "flat-cache": "^6.1.4",
-    "glob": "^10.1.0",
+    "glob": "^11.0.0",
     "global-agent": "^3.0.0",
-    "got": "^13.0.0",
+    "got": "^14.0.0",
     "ignore": "^7.0.0",
     "is-url": "^1.2.4",
     "js-yaml": "^4.0.0",
     "json5": "^2.2.0",
-    "minimatch": "^9.0.0",
+    "minimatch": "^10.0.0",
+    "p-limit": "^6.2.0",
+    "p-mutex": "^1.0.0",
     "smol-toml": "^1.0.1",
-    "yargs": "^17.0.1"
+    "yargs": "^18.0.0"
   },
   "devDependencies": {
     "c8": "^10.1.2",
     "eslint": "^9.9.0",
     "eslint-config-prettier": "^10.1.2",
-    "eslint-plugin-jsdoc": "^50.2.2",
-    "eslint-plugin-mocha": "^10.0.3",
+    "eslint-plugin-jsdoc": "^51.4.1",
+    "eslint-plugin-mocha": "^11.0.0",
     "eslint-plugin-prettier": "^5.0.0",
     "mocha": "^11.0.1",
     "mock-cwd": "^1.0.0",
@@ -59,7 +61,7 @@
     "prettier-plugin-jsdoc": "^1.3.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "type": "module",
   "keywords": [

package/src/bootstrap.js

@@ -53,8 +53,8 @@ function mergeConfigs(args, config) {
   if (config.filepath) {
     mergedConfig.configFileRelativePath = getRelativeFilePath(config);
   }
-  // https://github.com/chris48s/v8r/issues/494
-  delete mergedConfig.format;
+  // hard-coded - this can't be set via CLI or config file
+  mergedConfig.cachePrewarm = true;
   return mergedConfig;
 }
 
@@ -81,7 +81,7 @@ function parseArgs(argv, config, documentFormats, outputFormats) {
   const ignoreFilesOpts = {
     describe: "A list of files containing glob patterns to ignore",
   };
-  let ignoreFilesDefault = [".v8rignore"];
+  let ignoreFilesDefault = [".v8rignore", ".gitignore"];
   ignoreFilesOpts.defaultDescription = `${JSON.stringify(ignoreFilesDefault)}`;
   if (Object.keys(config.config).includes("ignorePatternFiles")) {
     ignoreFilesDefault = config.config.ignorePatternFiles;
@@ -122,13 +122,6 @@ function parseArgs(argv, config, documentFormats, outputFormats) {
         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(
@@ -190,10 +183,7 @@ function parseArgs(argv, config, documentFormats, outputFormats) {
       type: "string",
       choices: outputFormats,
       default: "text",
-      // https://github.com/chris48s/v8r/issues/494
-      describe:
-        "Output format for validation results. The '--format' alias is deprecated.",
-      alias: "format",
+      describe: "Output format for validation results",
     })
     .example([
       ["$0 file.json", "Validate a single file"],
@@ -251,14 +241,6 @@ 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 } =
@@ -274,11 +256,6 @@ 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-prewarm.js

@@ -0,0 +1,87 @@
+import isUrl from "is-url";
+import pLimit from "p-limit";
+import { getCatalogs, getMatchForFilename } from "./catalogs.js";
+
+const limit = pLimit(10);
+
+async function fetch(location, cache) {
+  return await cache.fetch(location, false);
+}
+
+function fetchWithLimit(url, cache) {
+  return limit(() => fetch(url, cache));
+}
+
+function normalizeUrl(ref) {
+  try {
+    const url = new URL(ref);
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+function getRemoteRefs(node) {
+  let refs = [];
+  if (Array.isArray(node)) {
+    for (const v of node) {
+      if (typeof v === "object" && v !== null) {
+        refs = refs.concat(getRemoteRefs(v));
+      }
+    }
+  } else if (typeof node === "object" && node !== null) {
+    for (const [k, v] of Object.entries(node)) {
+      if (k === "$ref" && typeof v === "string") {
+        const resolved = normalizeUrl(v);
+        if (resolved && isUrl(resolved)) {
+          refs.push(resolved);
+        }
+      }
+      if (typeof v === "object" && v !== null) {
+        refs = refs.concat(getRemoteRefs(v));
+      }
+    }
+  }
+  return Array.from(new Set(refs));
+}
+
+async function fetchAndRecurse(url, cache) {
+  const schema = await fetchWithLimit(url, cache);
+  const refs = getRemoteRefs(schema).filter(
+    (ref) => cache.get(ref) === undefined,
+  );
+  await Promise.all(refs.map((ref) => fetchAndRecurse(ref, cache)));
+}
+
+async function prewarmSchemaCache(filenames, config, cache) {
+  const catalogs = getCatalogs(config);
+  const schemaLocations = new Set();
+
+  for (const filename of filenames) {
+    let catalogMatch;
+    try {
+      catalogMatch = config.schema
+        ? {}
+        : await getMatchForFilename(catalogs, filename, "debug", cache);
+    } catch {
+      catalogMatch = {};
+    }
+    const schemaLocation = config.schema || catalogMatch.location;
+
+    if (schemaLocation) {
+      schemaLocations.add(schemaLocation);
+    }
+    cache.resetCounters();
+  }
+
+  await Promise.all(
+    Array.from(schemaLocations)
+      .filter((schemaLocation) => isUrl(schemaLocation))
+      .map((url) => fetchAndRecurse(url, cache)),
+  );
+  cache.persist();
+  cache.resetCounters();
+}
+
+export { getRemoteRefs, prewarmSchemaCache, normalizeUrl };

package/src/cache.js

@@ -1,4 +1,5 @@
 import got from "got";
+import Mutex from "p-mutex";
 import logger from "./logger.js";
 import { parseSchema } from "./parser.js";
 
@@ -7,39 +8,53 @@ class Cache {
     this.cache = flatCache;
     this.ttl = this.cache._cache.ttl || 0;
     this.callCounter = {};
+    this.locks = {};
     this.callLimit = 10;
     if (this.ttl === 0) {
       this.cache.clear();
     }
   }
 
-  limitDepth(url) {
+  getMutex(url) {
+    if (!(url in this.locks)) {
+      this.locks[url] = new Mutex();
+    }
+    return this.locks[url];
+  }
+
+  async limitDepth(url) {
     /*
     It is possible to create cyclic dependencies with external references
-    in JSON schema. Ajv doesn't detect this when resolving external references,
+    in JSON schema.
+    We try to mitigate this issue during cache pre-warming.
+    Ajv doesn't detect this when resolving external references,
     so we keep a count of how many times we've called the same URL.
     If we are calling the same URL over and over we've probably hit a circular
     external reference and we need to break the loop.
     */
-    if (url in this.callCounter) {
-      this.callCounter[url]++;
-    } else {
-      this.callCounter[url] = 1;
-    }
-    if (this.callCounter[url] > this.callLimit) {
-      throw new Error(
-        `Called ${url} >${this.callLimit} times. Possible circular reference.`,
-      );
-    }
+    const mutex = this.getMutex(url);
+
+    await mutex.withLock(async () => {
+      if (url in this.callCounter) {
+        this.callCounter[url]++;
+      } else {
+        this.callCounter[url] = 1;
+      }
+      if (this.callCounter[url] > this.callLimit) {
+        throw new Error(
+          `Called ${url} >${this.callLimit} times. Possible circular reference.`,
+        );
+      }
+    });
   }
 
   resetCounters() {
     this.callCounter = {};
   }
 
-  async fetch(url) {
-    this.limitDepth(url);
-    const cachedResponse = this.cache.getKey(url);
+  async fetch(url, persist = true) {
+    await this.limitDepth(url);
+    const cachedResponse = this.cache.get(url);
     if (cachedResponse !== undefined) {
       logger.debug(`Cache hit: using cached response from ${url}`);
       return cachedResponse.body;
@@ -50,8 +65,10 @@ class Cache {
       const resp = await got(url);
       const parsedBody = parseSchema(resp.body, url);
       if (this.ttl > 0) {
-        this.cache.setKey(url, { body: parsedBody });
-        this.cache.save(true);
+        this.cache.set(url, { body: parsedBody });
+        if (persist) {
+          this.cache.save(true);
+        }
       }
       return parsedBody;
     } catch (error) {
@@ -61,6 +78,14 @@ class Cache {
       throw new Error(`Failed fetching ${url}`);
     }
   }
+
+  persist() {
+    this.cache.save(true);
+  }
+
+  get(key) {
+    return this.cache.get(key);
+  }
 }
 
 export { Cache };

package/src/catalogs.js

@@ -74,7 +74,7 @@ function getMultipleMatchesLogMessage(matches) {
     .join("\n");
 }
 
-async function getMatchForFilename(catalogs, filename, cache) {
+async function getMatchForFilename(catalogs, filename, logLevel, cache) {
   for (const [i, rec] of catalogs.entries()) {
     const catalogLocation = rec.location;
     const catalog =
@@ -107,7 +107,7 @@ async function getMatchForFilename(catalogs, filename, cache) {
       (matches.length === 1 && matches[0].versions == null) ||
       (matches.length === 1 && Object.keys(matches[0].versions).length === 1)
     ) {
-      logger.info(`Found schema in ${catalogLocation} ...`);
+      logger[logLevel](`Found schema in ${catalogLocation} ...`);
       return coerceMatch(matches[0]); // Exactly one match found. We're done.
     }
 
@@ -122,7 +122,7 @@ async function getMatchForFilename(catalogs, filename, cache) {
     ) {
       // We found >1 matches in the same catalog. This is always a hard error.
       const matchesLog = getMultipleMatchesLogMessage(matches);
-      logger.info(
+      logger[logLevel](
         `Found multiple possible matches for ${filename}. Possible matches:\n\n${matchesLog}`,
       );
       throw new Error(

package/src/cli.js

@@ -12,6 +12,7 @@ import { getFromUrlOrFile } from "./io.js";
 import logger from "./logger.js";
 import { getDocumentLocation } from "./output-formatters.js";
 import { parseFile } from "./parser.js";
+import { prewarmSchemaCache } from "./cache-prewarm.js";
 
 const EXIT = {
   VALID: 0,
@@ -92,7 +93,7 @@ async function validateFile(filename, config, plugins, cache) {
     const catalogs = getCatalogs(config);
     const catalogMatch = config.schema
       ? {}
-      : await getMatchForFilename(catalogs, filename, cache);
+      : await getMatchForFilename(catalogs, filename, "info", cache);
     schemaLocation = config.schema || catalogMatch.location;
     schema = await getFromUrlOrFile(schemaLocation, cache);
     logger.info(
@@ -144,7 +145,6 @@ async function validateFile(filename, config, plugins, cache) {
     for (const plugin of plugins) {
       const message = plugin.getSingleResultLogMessage(
         result,
-        filename,
         config.outputFormat,
       );
       if (message != null) {
@@ -183,6 +183,12 @@ function Validator() {
     const ttl = secondsToMilliseconds(config.cacheTtl || 0);
     const cache = new Cache(getFlatCache(ttl));
 
+    if (config.cachePrewarm && ttl > 5000) {
+      logger.info("Pre-warming the cache");
+      await prewarmSchemaCache(filenames, config, cache);
+      logger.debug("Cache pre-warming complete");
+    }
+
     let results = [];
     for (const filename of filenames) {
       const fileResults = await validateFile(filename, config, plugins, cache);

package/src/glob.js

@@ -43,10 +43,6 @@ async function readIgnoreFiles(filenames) {
   return content;
 }
 
-function getSeparator() {
-  return process.platform == "win32" ? "\\" : "/";
-}
-
 async function getFiles(patterns, ignorePatternFiles) {
   let filenames = [];
 
@@ -80,10 +76,6 @@ async function getFiles(patterns, ignorePatternFiles) {
     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;
 }
 

package/src/parser.js

@@ -10,6 +10,9 @@ function parseFile(plugins, contents, filename, parser) {
       const maybeDocuments = Array.isArray(parsedFile)
         ? parsedFile
         : [parsedFile];
+      if (maybeDocuments.length === 0) {
+        throw new Error(`No documents to validate found in ${filename}`);
+      }
       for (const doc of maybeDocuments) {
         if (!(doc instanceof Document)) {
           throw new Error(

package/src/plugins/output-text.js

@@ -8,7 +8,7 @@ class TextOutput extends BasePlugin {
     return ["text"];
   }
 
-  getSingleResultLogMessage(result, fileLocation, format) {
+  getSingleResultLogMessage(result, format) {
     if (result.valid === false && format === "text") {
       return formatErrors(getDocumentLocation(result), result.errors);
     }

package/src/plugins.js

@@ -1,5 +1,4 @@
 import path from "node:path";
-import logger from "./logger.js";
 
 /**
  * Base class for all v8r plugins.
@@ -37,10 +36,7 @@ class BasePlugin {
    * Document object or an array of Document objects.
    *
    * @param {string} contents - The unparsed file content.
-   * @param {string} fileLocation - The file path. 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.
+   * @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.
@@ -76,16 +72,12 @@ class BasePlugin {
    *
    * @param {ValidationResult} result - Result of attempting to validate this
    *   document.
-   * @param {string} fileLocation - The document file path. 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.
    * @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, fileLocation, format) {
+  getSingleResultLogMessage(result, format) {
     return undefined;
   }
 
@@ -124,11 +116,7 @@ class Document {
   }
 }
 
-function hasProperty(plugin, prop) {
-  return Object.prototype.hasOwnProperty.call(plugin.prototype, prop);
-}
-
-function validatePlugin(plugin, warnings) {
+function validatePlugin(plugin) {
   if (
     typeof plugin.name !== "string" ||
     !plugin.name.startsWith("v8r-plugin-")
@@ -155,29 +143,6 @@ function validatePlugin(plugin, warnings) {
       );
     }
   }
-
-  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) {
@@ -193,19 +158,19 @@ function resolveUserPlugins(userPlugins) {
   return plugins;
 }
 
-async function loadPlugins(plugins, warnings) {
+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, warnings));
+  loadedPlugins.forEach((plugin) => validatePlugin(plugin));
   loadedPlugins = loadedPlugins.map((plugin) => new plugin());
   return loadedPlugins;
 }
 
 async function loadAllPlugins(userPlugins) {
-  const loadedUserPlugins = await loadPlugins(userPlugins, true);
+  const loadedUserPlugins = await loadPlugins(userPlugins);
 
   const corePlugins = [
     "./plugins/parser-json.js",
@@ -215,7 +180,7 @@ async function loadAllPlugins(userPlugins) {
     "./plugins/output-text.js",
     "./plugins/output-json.js",
   ];
-  const loadedCorePlugins = await loadPlugins(corePlugins, false);
+  const loadedCorePlugins = await loadPlugins(corePlugins);
 
   return {
     allLoadedPlugins: loadedUserPlugins.concat(loadedCorePlugins),
@@ -227,10 +192,6 @@ async function loadAllPlugins(userPlugins) {
 /**
  * @typedef {object} ValidationResult
  * @property {string} fileLocation - Path of the document that was validated.
- *   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,

package/src/test-helpers.js

@@ -1,4 +1,3 @@
-import { clearCacheById } from "flat-cache";
 import logger from "./logger.js";
 
 const origWriteOut = logger.writeOut;
@@ -7,7 +6,6 @@ const testCacheName = process.env.V8R_CACHE_NAME;
 const env = process.env;
 
 function setUp() {
-  clearCacheById(testCacheName);
   logger.resetStdout();
   logger.resetStderr();
   logger.writeOut = function () {};
@@ -16,7 +14,6 @@ function setUp() {
 }
 
 function tearDown() {
-  clearCacheById(testCacheName);
   logger.resetStdout();
   logger.resetStderr();
   logger.writeOut = origWriteOut;