doc-detective-common 3.0.0-dev.4 → 3.0.0

package/README.md

@@ -1,85 +0,0 @@
-# Doc Detective Common
-
-![Current version](https://img.shields.io/github/package-json/v/doc-detective/doc-detective-common?color=orange)
-[![NPM Shield](https://img.shields.io/npm/v/doc-detective-common)](https://www.npmjs.com/package/doc-detective-common)
-[![Discord Shield](https://img.shields.io/badge/chat-on%20discord-purple)](https://discord.gg/mSCCRAhH)
-
-Shared resources for Doc Detective projects.
-
-## Install
-
-```bash
-npm i doc-detective-common
-```
-
-## Init
-
-```javascript
-const common = require("doc-detective-common");
-```
-
-## Methods
-
-### `.validate(schemaKey: string, object: object)`
-
-Validate that `object` matches the specified [schema](#.schemas) definition.
-
-Returns an object with the following schema:
-
-```json
-{
-  "valid": boolean,
-  "errors": [
-    {
-      "instancePath": string,
-      "schemaPath": string,
-      "keyword": string,
-      "params": [{Object}],
-      "message": string
-    }
-  ]
-}
-```
-
-#### Usage
-
-```js
-const schemaKey = "runShell_v1";
-const object = {
-  action: "runShell",
-  command: "echo $username",
-};
-console.log(common.validate(schemaKey, object));
-```
-
-### `.readFile(fileURL)`
-
-Load file contents from a URL or a file path. If a JSON or YAML file, returns an object. If a different file, returns a string.
-
-## Objects
-
-### `.schemas`
-
-JSON schema definitions for various objects used throughout Doc Detective.
-
-Schema objects are located in the [`/schemas`](https://github.com/doc-detective/doc-detective-common/tree/schema/schemas) directory and made available through the `.schemas` object.
-
-```json
-{
-  "analytics_v1": {Object},
-  "checkLink_v1": {Object},
-  "click_v1": {Object},
-  "find_v1": {Object},
-  "goTo_v1": {Object},
-  "httpRequest_v1": {Object},
-  "matchText_v1": {Object},
-  "moveMouse_v1": {Object},
-  "runShell_v1": {Object},
-  "screenshot_v1": {Object},
-  "scroll_v1": {Object},
-  "startRecording_v1": {Object},
-  "stopRecording_v1": {Object},
-  "type_v1": {Object},
-  "wait_v1": {Object}
-}
-```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc-detective-common",
-  "version": "3.0.0-dev.4",
+  "version": "3.0.0",
   "description": "Shared components for Doc Detective projects.",
   "main": "src/index.js",
   "scripts": {

package/src/files.js

@@ -4,13 +4,15 @@ const axios = require("axios");
 const { URL } = require("url");
 
 /**
- * Reads a file from a given URL or local file path and returns its content.
- * Supports JSON and YAML file formats.
+ * Reads and parses content from a remote URL or local file path, supporting JSON and YAML formats.
  *
- * @param {string} fileURLOrPath - The URL or local file path of the file to read.
- * @returns {Promise<Object|string|null>} - The parsed content of the file if it's JSON or YAML,
- *                                          the raw content if it's another format,
- *                                          or null if an error occurs.
+ * Attempts to parse the file content as JSON first, then YAML. If both parsing attempts fail, returns the raw content as a string. Returns `null` if the file cannot be read.
+ *
+ * @param {Object} options
+ * @param {string} options.fileURLOrPath - The URL or local file path to read.
+ * @returns {Promise<Object|string|null>} Parsed object for JSON or YAML files, raw string for other formats, or `null` if reading fails.
+ *
+ * @throws {Error} If {@link fileURLOrPath} is missing, not a string, or is an empty string.
  */
 async function readFile({ fileURLOrPath }) {
   if (!fileURLOrPath) {

package/src/resolvePaths.js

@@ -5,21 +5,19 @@ const { validate } = require("./validate");
 exports.resolvePaths = resolvePaths;
 
 /**
- * Resolves relative paths in configuration and specification objects to absolute paths.
+ * Recursively resolves all relative path properties in a configuration or specification object to absolute paths.
  *
- * This function traverses an object (either a config or spec) and converts all path properties
- * to absolute paths based on the provided configuration and file path. It can handle nested objects
- * and special path relationships like path/directory and savePath/saveDirectory.
+ * Traverses the provided object, converting all recognized path-related properties to absolute paths using the given configuration and reference file path. Supports nested objects and distinguishes between config and spec objects based on schema validation. Throws an error if the object is not a valid config or spec, or if the object type is missing for nested objects.
  *
  * @async
- * @param {Object} options - The options object.
- * @param {Object} options.config - The configuration object containing settings like relativePathBase.
- * @param {Object} options.object - The object whose paths need to be resolved.
- * @param {string} options.filePath - The reference file path for resolving relative paths.
- * @param {boolean} [options.nested=false] - Flag indicating if this is a recursive call for a nested object.
- * @param {string} [options.objectType] - The type of object ('config' or 'spec'). Required for nested objects.
- * @returns {Promise<Object>} The object with all paths resolved to absolute paths.
- * @throws {Error} Throws an error if the object isn't a valid config or spec, or if objectType is missing for nested objects.
+ * @param {Object} options - Options for path resolution.
+ * @param {Object} options.config - Configuration object containing settings such as `relativePathBase`.
+ * @param {Object} options.object - The config or spec object whose path properties will be resolved.
+ * @param {string} options.filePath - Reference file path used for resolving relative paths.
+ * @param {boolean} [options.nested=false] - Indicates if this is a recursive call for a nested object.
+ * @param {string} [options.objectType] - Specifies the object type ('config' or 'spec'); required for nested objects.
+ * @returns {Promise<Object>} The object with all applicable path properties resolved to absolute paths.
+ * @throws {Error} If the object is neither a valid config nor spec, or if `objectType` is missing for nested objects.
  */
 async function resolvePaths({
   config,
@@ -66,12 +64,14 @@ async function resolvePaths({
   ];
 
   /**
-   * Resolves a path based on the provided base type, relative path, and file path.
+   * Resolves a relative path to an absolute path using a specified base type and reference file path.
    *
-   * @param {string} baseType - The base type of the path ("file" or "cwd").
-   * @param {string} relativePath - The relative path to resolve.
-   * @param {string} filePath - The file path to use as a reference.
-   * @returns {string} - The resolved path.
+   * @param {string} baseType - Indicates whether to resolve relative to the reference file's directory ("file") or the current working directory ("cwd").
+   * @param {string} relativePath - The path to resolve, which may be relative or absolute.
+   * @param {string} filePath - The reference file or directory path used for resolution.
+   * @returns {string} The absolute path corresponding to {@link relativePath}.
+   *
+   * @remark If {@link relativePath} is already absolute, it is returned unchanged. If {@link filePath} does not exist, its extension is used to infer whether it is a file or directory.
    */
   function resolve(baseType, relativePath, filePath) {
     // If path is already absolute, return it

package/src/schemas/dereferenceSchemas.js

@@ -6,9 +6,12 @@ const fs = require("fs");
   await dereferenceSchemas();
 })();
 
-/*
- * Walks through all schema in src/src_schema
- * For each schema, dereferences it and writes it to src/schema
+/**
+ * Processes JSON schema files by updating reference paths, dereferencing all `$ref` pointers, and generating fully resolved schema outputs.
+ *
+ * For each schema in the input directory, this function updates reference paths, writes intermediate schemas to a build directory, dereferences all references, removes `$id` properties, and writes the final schemas to an output directory. It also creates a consolidated `schemas.json` file containing all dereferenced schemas keyed by filename.
+ *
+ * @remark The function assumes all schema files listed exist in the input directory and does not handle missing files or invalid JSON beyond throwing synchronous errors.
  */
 async function dereferenceSchemas() {
   const inputDir = path.resolve(`${__dirname}/src_schemas`);
@@ -127,7 +130,12 @@ function updateRefPaths(schema) {
   return schema;
 }
 
-// Prepend app-root path to referenced relative paths
+/**
+ * Recursively removes all `$id` properties from a JSON schema object.
+ *
+ * @param {object} schema - The JSON schema object to process.
+ * @returns {object} The schema object with all `$id` properties deleted.
+ */
 function deleteDollarIds(schema) {
   for (let [key, value] of Object.entries(schema)) {
     if (typeof value === "object") {

package/src/schemas/output_schemas/checkLink_v3.schema.json

@@ -5,7 +5,7 @@
     {
       "description": "Check if an HTTP or HTTPS URL returns an acceptable status code from a GET request.",
       "type": "string",
-      "pattern": "(^(http://|https://|/).*|\\$[A-Za-z0-9_]+)",
+      "pattern": "(^(http://|https://|\\/).*|\\$[A-Za-z0-9_]+$)",
       "transform": [
         "trim"
       ]
@@ -66,7 +66,7 @@
       "string": {
         "description": "Check if an HTTP or HTTPS URL returns an acceptable status code from a GET request.",
         "type": "string",
-        "pattern": "(^(http://|https://|/).*|\\$[A-Za-z0-9_]+)",
+        "pattern": "(^(http://|https://|\\/).*|\\$[A-Za-z0-9_]+$)",
         "transform": [
           "trim"
         ]

package/src/schemas/output_schemas/click_v3.schema.json

@@ -14,6 +14,20 @@
     },
     {
       "type": "object",
+      "anyOf": [
+        {
+          "required": [
+            "button",
+            "selector"
+          ]
+        },
+        {
+          "required": [
+            "button",
+            "elementText"
+          ]
+        }
+      ],
       "properties": {
         "button": {
           "description": "Kind of click to perform.",
@@ -35,8 +49,7 @@
       }
     },
     {
-      "type": "boolean",
-      "nullable": true
+      "type": "boolean"
     }
   ],
   "components": {
@@ -52,6 +65,20 @@
       },
       "object": {
         "type": "object",
+        "anyOf": [
+          {
+            "required": [
+              "button",
+              "selector"
+            ]
+          },
+          {
+            "required": [
+              "button",
+              "elementText"
+            ]
+          }
+        ],
         "properties": {
           "button": {
             "description": "Kind of click to perform.",