v8r 4.0.1 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 📦 [4.2.0](https://www.npmjs.com/package/v8r/v/4.2.0) - 2024-10-24
+
+* Add `V8R_CONFIG_FILE` environment variable.
+  This allows loading a config file from a location other than the directory v8r is invoked from.
+  More info: https://chris48s.github.io/v8r/configuration/
+
+## 📦 [4.1.0](https://www.npmjs.com/package/v8r/v/4.1.0) - 2024-08-25
+
+* v8r can now parse and validate files that contain multiple yaml documents
+  More info: https://chris48s.github.io/v8r/usage-examples/#files-containing-multiple-documents
+* The `parseInputFile()` plugin hook may now conditionally return an array of `Document` objects
+* The `ValidationResult` object now contains a `documentIndex` property.
+  This identifies the document when a multi-doc file has been validated.
+
 ## 📦 [4.0.1](https://www.npmjs.com/package/v8r/v/4.0.1) - 2024-08-19
 
 * De-duplicate and sort files before validating

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "v8r",
-  "version": "4.0.1",
+  "version": "4.2.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\"",

package/src/ajv.js

@@ -1,4 +1,4 @@
-import { createRequire } from "module";
+import { createRequire } from "node: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);

package/src/bootstrap.js

@@ -1,12 +1,12 @@
-import { createRequire } from "module";
+import { createRequire } from "node: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 fs from "node:fs";
+import path from "node:path";
 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 {
@@ -17,27 +17,28 @@ import {
 import logger from "./logger.js";
 import { loadAllPlugins, resolveUserPlugins } from "./plugins.js";
 
-function preProcessConfig(configFile) {
-  if (!configFile?.config?.customCatalog?.schemas) {
-    return;
-  }
-  for (const schema of configFile.config.customCatalog.schemas) {
-    if (!path.isAbsolute(schema.location) && !isUrl(schema.location)) {
-      schema.location = path.join(
-        path.dirname(configFile.filepath),
-        schema.location,
-      );
+async function getCosmiConfig(cosmiconfigOptions) {
+  let configFile;
+
+  if (process.env.V8R_CONFIG_FILE) {
+    if (!fs.existsSync(process.env.V8R_CONFIG_FILE)) {
+      throw new Error(`File ${process.env.V8R_CONFIG_FILE} does not exist.`);
     }
+    configFile = await cosmiconfig("v8r", cosmiconfigOptions).load(
+      process.env.V8R_CONFIG_FILE,
+    );
+  } else {
+    cosmiconfigOptions.stopDir = process.cwd();
+    configFile = (await cosmiconfig("v8r", cosmiconfigOptions).search(
+      process.cwd(),
+    )) || { config: {} };
   }
-}
 
-async function getCosmiConfig(cosmiconfigOptions) {
-  cosmiconfigOptions.stopDir = process.cwd();
-  const configFile = (await cosmiconfig("v8r", cosmiconfigOptions).search(
-    process.cwd(),
-  )) || { config: {} };
   if (configFile.filepath) {
     logger.info(`Loaded config file from ${getRelativeFilePath(configFile)}`);
+    logger.info(
+      `Patterns and relative paths will be resolved relative to current working directory: ${process.cwd()}`,
+    );
   } else {
     logger.info(`No config file found`);
   }
@@ -200,7 +201,6 @@ async function bootstrap(argv, config, cosmiconfigOptions = {}) {
   // 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);
@@ -213,10 +213,4 @@ async function bootstrap(argv, config, cosmiconfigOptions = {}) {
   };
 }
 
-export {
-  bootstrap,
-  getDocumentFormats,
-  getOutputFormats,
-  parseArgs,
-  preProcessConfig,
-};
+export { bootstrap, getDocumentFormats, getOutputFormats, parseArgs };

package/src/catalogs.js

@@ -1,5 +1,5 @@
+import path from "node:path";
 import { minimatch } from "minimatch";
-import path from "path";
 import { validate } from "./ajv.js";
 import { getFromUrlOrFile } from "./io.js";
 import logger from "./logger.js";

package/src/cli.js

@@ -1,7 +1,7 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import flatCache from "flat-cache";
-import fs from "fs";
-import os from "os";
-import path from "path";
 import isUrl from "is-url";
 import { validate } from "./ajv.js";
 import { bootstrap } from "./bootstrap.js";
@@ -10,6 +10,7 @@ import { getCatalogs, getMatchForFilename } from "./catalogs.js";
 import { getFiles } from "./glob.js";
 import { getFromUrlOrFile } from "./io.js";
 import logger from "./logger.js";
+import { getDocumentLocation } from "./output-formatters.js";
 import { parseFile } from "./parser.js";
 
 const EXIT = {
@@ -33,61 +34,122 @@ function getFlatCache() {
   return flatCache.load("v8r", CACHE_DIR);
 }
 
-async function validateFile(filename, config, plugins, cache) {
-  logger.info(`Processing ${filename}`);
+async function validateDocument(
+  fileLocation,
+  documentIndex,
+  document,
+  schemaLocation,
+  schema,
+  strictMode,
+  cache,
+  resolver,
+) {
   let result = {
-    fileLocation: filename,
-    schemaLocation: null,
+    fileLocation,
+    documentIndex,
+    schemaLocation,
     valid: null,
     errors: [],
     code: null,
   };
+  try {
+    const { valid, errors } = await validate(
+      document,
+      schema,
+      strictMode,
+      cache,
+      resolver,
+    );
+    result.valid = valid;
+    result.errors = errors;
+
+    const documentLocation = getDocumentLocation(result);
+    if (valid) {
+      logger.success(`${documentLocation} is valid\n`);
+    } else {
+      logger.error(`${documentLocation} is invalid\n`);
+    }
+
+    result.code = valid ? EXIT.VALID : EXIT.INVALID;
+    return result;
+  } catch (e) {
+    logger.error(`${e.message}\n`);
+    result.code = EXIT.ERROR;
+    return result;
+  }
+}
+
+async function validateFile(filename, config, plugins, cache) {
+  logger.info(`Processing ${filename}`);
+
+  let schema, schemaLocation, documents, strictMode, resolver;
+
   try {
     const catalogs = getCatalogs(config);
     const catalogMatch = config.schema
       ? {}
       : await getMatchForFilename(catalogs, filename, cache);
-    const schemaLocation = config.schema || catalogMatch.location;
-    result.schemaLocation = schemaLocation;
-    const schema = await getFromUrlOrFile(schemaLocation, cache);
+    schemaLocation = config.schema || catalogMatch.location;
+    schema = await getFromUrlOrFile(schemaLocation, cache);
     logger.info(
       `Validating ${filename} against schema from ${schemaLocation} ...`,
     );
 
-    const data = parseFile(
+    documents = parseFile(
       plugins,
       await fs.promises.readFile(filename, "utf8"),
       filename,
       catalogMatch.parser,
     );
 
-    const strictMode = config.verbose >= 2 ? "log" : false;
-    const resolver = isUrl(schemaLocation)
+    strictMode = config.verbose >= 2 ? "log" : false;
+    resolver = isUrl(schemaLocation)
       ? (location) => getFromUrlOrFile(location, cache)
       : (location) =>
           getFromUrlOrFile(location, cache, path.dirname(schemaLocation));
-    const { valid, errors } = await validate(
-      data,
+  } catch (e) {
+    logger.error(`${e.message}\n`);
+    return [
+      {
+        fileLocation: filename,
+        documentIndex: null,
+        schemaLocation: schemaLocation || null,
+        valid: null,
+        errors: [],
+        code: EXIT.ERROR,
+      },
+    ];
+  }
+
+  let results = [];
+  for (let i = 0; i < documents.length; i++) {
+    const documentIndex = documents.length === 1 ? null : i;
+    const result = await validateDocument(
+      filename,
+      documentIndex,
+      documents[i],
+      schemaLocation,
       schema,
       strictMode,
       cache,
       resolver,
     );
-    result.valid = valid;
-    result.errors = errors;
-    if (valid) {
-      logger.success(`${filename} is valid\n`);
-    } else {
-      logger.error(`${filename} is invalid\n`);
-    }
 
-    result.code = valid ? EXIT.VALID : EXIT.INVALID;
-    return result;
-  } catch (e) {
-    logger.error(`${e.message}\n`);
-    result.code = EXIT.ERROR;
-    return result;
+    results.push(result);
+
+    for (const plugin of plugins) {
+      const message = plugin.getSingleResultLogMessage(
+        result,
+        filename,
+        config.format,
+      );
+      if (message != null) {
+        logger.log(message);
+        break;
+      }
+    }
   }
+  return results;
 }
 
 function resultsToStatusCode(results, ignoreErrors) {
@@ -122,21 +184,8 @@ function Validator() {
 
     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;
-        }
-      }
-
+      const fileResults = await validateFile(filename, config, plugins, cache);
+      results = results.concat(fileResults);
       cache.resetCounters();
     }
 

package/src/config-validators.js

@@ -1,4 +1,4 @@
-import { createRequire } from "module";
+import { createRequire } from "node: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);

package/src/io.js

@@ -1,5 +1,5 @@
-import fs from "fs";
-import path from "path";
+import fs from "node:fs";
+import path from "node:path";
 import isUrl from "is-url";
 import { parseSchema } from "./parser.js";
 

package/src/output-formatters.js

@@ -1,13 +1,20 @@
 import Ajv from "ajv";
 
-function formatErrors(filename, errors) {
+function getDocumentLocation(result) {
+  if (result.documentIndex == null) {
+    return result.fileLocation;
+  }
+  return `${result.fileLocation}[${result.documentIndex}]`;
+}
+
+function formatErrors(location, errors) {
   const ajv = new Ajv();
   return (
     ajv.errorsText(errors, {
       separator: "\n",
-      dataVar: filename + "#",
+      dataVar: location + "#",
     }) + "\n"
   );
 }
 
-export { formatErrors };
+export { formatErrors, getDocumentLocation };

package/src/parser.js

@@ -1,17 +1,23 @@
-import path from "path";
+import path from "node:path";
 import yaml from "js-yaml";
 import { Document } from "./plugins.js";
 
 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}`,
-        );
+    const parsedFile = plugin.parseInputFile(contents, filename, parser);
+
+    if (parsedFile != null) {
+      const maybeDocuments = Array.isArray(parsedFile)
+        ? parsedFile
+        : [parsedFile];
+      for (const doc of maybeDocuments) {
+        if (!(doc instanceof Document)) {
+          throw new Error(
+            `Plugin ${plugin.constructor.name} returned an unexpected type from parseInputFile hook. Expected Document, got ${typeof doc}`,
+          );
+        }
       }
-      return result.document;
+      return maybeDocuments.map((md) => md.document);
     }
   }
 

package/src/plugins/output-text.js

@@ -1,5 +1,5 @@
 import { BasePlugin } from "../plugins.js";
-import { formatErrors } from "../output-formatters.js";
+import { formatErrors, getDocumentLocation } from "../output-formatters.js";
 
 class TextOutput extends BasePlugin {
   static name = "v8r-plugin-text-output";
@@ -10,7 +10,7 @@ class TextOutput extends BasePlugin {
 
   getSingleResultLogMessage(result, fileLocation, format) {
     if (result.valid === false && format === "text") {
-      return formatErrors(fileLocation, result.errors);
+      return formatErrors(getDocumentLocation(result), result.errors);
     }
   }
 }

package/src/plugins/parser-yaml.js

@@ -10,10 +10,10 @@ class YamlParser extends BasePlugin {
 
   parseInputFile(contents, fileLocation, parser) {
     if (parser === "yaml") {
-      return new Document(yaml.load(contents));
+      return yaml.loadAll(contents).map((doc) => new Document(doc));
     } else if (parser == null) {
       if (fileLocation.endsWith(".yaml") || fileLocation.endsWith(".yml")) {
-        return new Document(yaml.load(contents));
+        return yaml.loadAll(contents).map((doc) => new Document(doc));
       }
     }
   }

package/src/plugins.js

@@ -1,4 +1,4 @@
-import path from "path";
+import path from "node:path";
 
 /**
  * Base class for all v8r plugins.
@@ -32,7 +32,8 @@ class BasePlugin {
    * 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 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. Filenames are resolved and
@@ -43,7 +44,7 @@ class BasePlugin {
    * @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
+   * @returns {Document | Document[] | undefined} Parsed file contents
    */
   // eslint-disable-next-line no-unused-vars
   parseInputFile(contents, fileLocation, parser) {
@@ -205,6 +206,12 @@ async function loadAllPlugins(userPlugins) {
  *   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,
+ *   `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

package/src/test-helpers.js

@@ -4,6 +4,7 @@ import logger from "./logger.js";
 const origWriteOut = logger.writeOut;
 const origWriteErr = logger.writeErr;
 const testCacheName = process.env.V8R_CACHE_NAME;
+const env = process.env;
 
 function setUp() {
   flatCache.clearCacheById(testCacheName);
@@ -11,6 +12,7 @@ function setUp() {
   logger.resetStderr();
   logger.writeOut = function () {};
   logger.writeErr = function () {};
+  process.env = { ...env };
 }
 
 function tearDown() {
@@ -19,6 +21,7 @@ function tearDown() {
   logger.resetStderr();
   logger.writeOut = origWriteOut;
   logger.writeErr = origWriteErr;
+  process.env = env;
 }
 
 function isString(el) {