doc-detective 2.17.1-dev.0 → 2.18.0-dev.0

package/README.md

@@ -33,14 +33,7 @@ Doc Detective has multiple components to integrate with your workflows as you ne
 
     If you don't install Doc Detective globally, you'll be prompted to install the first time you run an `npx` command.
 
-## (Optional) Get sample files
-
-To test a few samples, clone the repo and navigate to the `samples` directory:
-
-```bash
-git clone https://github.com/doc-detective/doc-detective.git
-cd doc-detective/samples
-```
+    **Note:** If you're working in a cloned `doc-detective` repository, run `npm i` to install local dependencies or the `npx` command in the next step will fail.
 
 ## Run tests
 
@@ -56,7 +49,7 @@ By default, Doc Detective scans the current directory for valid tests, but you c
 npx doc-detective runTests --input doc-content-inline-tests.md
 ```
 
-To customize your test, file type, and directory options, create a `.doc-detective.json` [config](https://doc-detective.com/reference/schemas/config.html) file. If a `.doc-detective.json` file exists in the directory when you run the comment, Doc Detective loads the config. Otherwise, you can specify a config path with the `--config` argument.
+To customize your test, file type, and directory options, create a `.doc-detective.json` [config](https://doc-detective.com/docs/references/schemas/config.html) file. If a `.doc-detective.json` file exists in the directory when you run the comment, Doc Detective loads the config. Otherwise, you can specify a config path with the `--config` argument.
 
 ```bash
 npx doc-detective runTests --config .doc-detective.json
@@ -70,9 +63,13 @@ You can override config options with command-line arguments. For example, to run
 npx doc-detective runTests --config .doc-detective.json --input tests.spec.json
 ```
 
+### Check out some samples
+
+You can find test and config samples in the [samples](https://github.com/doc-detective/doc-detective/tree/main/samples) directory.
+
 ## Check your test coverage
 
-You can check the test coverage of your documentation source files with the `runCoverage` command, specifying the source file or directory of source files with the `--input` argument. Doc Detective identifies potential areas of test coverage with file-format-specific regex, and supports CommonMark syntax natively. If you want to test coverage of a file with different syntax, update your the `fileTypes` object of your [config](https://doc-detective.com/reference/schemas/config.html) file accordingly.
+You can check the test coverage of your documentation source files with the `runCoverage` command, specifying the source file or directory of source files with the `--input` argument. Doc Detective identifies potential areas of test coverage with file-format-specific regex, and supports CommonMark syntax natively. If you want to test coverage of a file with different syntax, update the `fileTypes` object of your [config](https://doc-detective.com/docs/references/schemas/config.html) file accordingly.
 
 ```bash
 npx doc-detective runCoverage --config .doc-detective.json --input doc-content.md
@@ -80,21 +77,21 @@ npx doc-detective runCoverage --config .doc-detective.json --input doc-content.m
 
 ## Concepts
 
-- [**Test specification**](https://doc-detective.com/reference/schemas/specification.html): A group of tests to run in one or more contexts. Conceptually parallel to a document.
-- [**Test**](https://doc-detective.com/reference/schemas/test.html): A sequence of steps to perform. Conceptually parallel to a procedure.
+- [**Test specification**](https://doc-detective.com/docs/references/schemas/specification.html): A group of tests to run in one or more contexts. Conceptually parallel to a document.
+- [**Test**](https://doc-detective.com/docs/references/schemas/test.html): A sequence of steps to perform. Conceptually parallel to a procedure.
 - **Step**: A portion of a test that includes a single action. Conceptually parallel to a step in a procedure.
 - **Action**: The task a performed in a step. Doc Detective supports a variety of actions:
-  - [**checkLink**](https://doc-detective.com/reference/schemas/checkLink.html): Check if a URL returns an acceptable status code from a GET request.
-  - [**find**](https://doc-detective.com/reference/schemas/find.html): Check if an element exists with the specified selector.
-  - [**goTo**](https://doc-detective.com/reference/schemas/goTo.html): Navigate to a specified URL.
-  - [**httpRequest**](https://doc-detective.com/reference/schemas/httpRequest.html): Perform a generic HTTP request, for example to an API.
-  - [**runShell**](https://doc-detective.com/reference/schemas/runShell.html): Perform a native shell command.
-  - [**saveScreenshot**](https://doc-detective.com/reference/schemas/saveScreenshot.html): Take a screenshot in PNG format.
-  - [**setVariables**](https://doc-detective.com/reference/schemas/setVariables.html): Load environment variables from a `.env` file.
-  - [**startRecording**](https://doc-detective.com/reference/schemas/startRecording.html) and [**stopRecording**](https://doc-detective.com/reference/schemas/stopRecording.html): Capture a video of test execution.
-  - [**typeKeys**](https://doc-detective.com/reference/schemas/typeKeys.html): Type keys. To type special keys, begin and end the string with `$` and use the special key’s enum. For example, to type the Escape key, enter `$ESCAPE$`.
-  - [**wait**](https://doc-detective.com/reference/schemas/wait.html): Pause before performing the next action.
-- [**Context**](https://doc-detective.com/reference/schemas/context.html): An application and platforms that support the tests.
+  - [**checkLink**](https://doc-detective.com/docs/references/schemas/checkLink.html): Check if a URL returns an acceptable status code from a GET request.
+  - [**find**](https://doc-detective.com/docs/references/schemas/find.html): Check if an element exists with the specified selector.
+  - [**goTo**](https://doc-detective.com/docs/references/schemas/goTo.html): Navigate to a specified URL.
+  - [**httpRequest**](https://doc-detective.com/docs/references/schemas/httpRequest.html): Perform a generic HTTP request, for example to an API.
+  - [**runShell**](https://doc-detective.com/docs/references/schemas/runShell.html): Perform a native shell command.
+  - [**saveScreenshot**](https://doc-detective.com/docs/references/schemas/saveScreenshot.html): Take a screenshot in PNG format.
+  - [**setVariables**](https://doc-detective.com/docs/references/schemas/setVariables.html): Load environment variables from a `.env` file.
+  - [**startRecording**](https://doc-detective.com/docs/references/schemas/startRecording.html) and [**stopRecording**](https://doc-detective.com/docs/references/schemas/stopRecording.html): Capture a video of test execution.
+  - [**typeKeys**](https://doc-detective.com/docs/references/schemas/typeKeys.html): Type keys. To type special keys, begin and end the string with `$` and use the special key’s enum. For example, to type the Escape key, enter `$ESCAPE$`.
+  - [**wait**](https://doc-detective.com/docs/references/schemas/wait.html): Pause before performing the next action.
+- [**Context**](https://doc-detective.com/docs/references/schemas/context.html): An application and platforms that support the tests.
 
 ## Roadmap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc-detective",
-  "version": "2.17.1-dev.0",
+  "version": "2.18.0-dev.0",
   "description": "Treat doc content as testable assertions to validate doc accuracy and product UX.",
   "bin": {
     "doc-detective": "src/index.js"
@@ -9,7 +9,9 @@
   "scripts": {
     "mocha": "mocha",
     "test": "mocha test/*.test.js",
+    "prerunTests": "node ./src/checkDependencies.js",
     "runTests": "node ./src/index.js runTests",
+    "prerunCoverage": "node ./src/checkDependencies.js",
     "runCoverage": "node ./src/index.js runCoverage",
     "dev": "node ./dev"
   },
@@ -32,8 +34,8 @@
   "homepage": "https://github.com/doc-detective/doc-detective#readme",
   "dependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
-    "doc-detective-common": "^1.20.0",
-    "doc-detective-core": "^2.17.1-dev.0",
+    "doc-detective-common": "^1.21.0",
+    "doc-detective-core": "^2.18.0",
     "prompt-sync": "^4.2.0",
     "yargs": "^17.7.2"
   },

package/samples/doc-content-detect.md

@@ -4,8 +4,8 @@
 
 - The landing page discusses what Doc Detective is, what it does, and who might find it useful.
 
-- [Get started](https://doc-detective.com/get-started.html) covers how to quickly get up and running with Doc Detective.
+- [Get started](https://doc-detective.com/docs/get-started.html) covers how to quickly get up and running with Doc Detective.
 
-- The [references](https://doc-detective.com/reference/) detail the various JSON objects that Doc Detective expects for [configs](https://doc-detective.com/reference/schemas/config.html), [test specifications](https://doc-detective.com/reference/schemas/specification.html), [tests](https://doc-detective.com/reference/schemas/test), actions, and more. Open [typeKeys](https://doc-detective.com/reference/schemas/typeKeys.html)--or any other schema--and you'll find three sections: **Description**, **Fields**, and **Examples**.
+- The [references](https://doc-detective.com/docs/category/schemas) detail the various JSON objects that Doc Detective expects for [configs](https://doc-detective.com/docs/references/schemas/config.html), [test specifications](https://doc-detective.com/docs/references/schemas/specification.html), [tests](https://doc-detective.com/docs/references/schemas/test), actions, and more. Open [typeKeys](https://doc-detective.com/docs/references/schemas/typeKeys.html)--or any other schema--and you'll find two sections: **Fields** and **Examples**.
 
 ![Search results.](reference.png)

package/samples/doc-content-inline-tests.md

@@ -8,18 +8,17 @@
 
 - The landing page discusses what Doc Detective is, what it does, and who might find it useful.
 
-- [Get started](https://doc-detective.com/get-started.html) covers how to quickly get up and running with Doc Detective.
+- [Get started](https://doc-detective.com/docs/get-started.html) covers how to quickly get up and running with Doc Detective.
 
-  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/get-started.html"})
+  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/docs/get-started.html"})
 
-- The [references](https://doc-detective.com/reference/) detail the various JSON objects that Doc Detective expects for [configs](https://doc-detective.com/reference/schemas/config.html), [test specifications](https://doc-detective.com/reference/schemas/specification.html), [tests](https://doc-detective.com/reference/schemas/test), actions, and more. Open [typeKeys](https://doc-detective.com/reference/schemas/typeKeys.html)--or any other schema--and you'll find three sections: **Description**, **Fields**, and **Examples**.
+- The [references](https://doc-detective.com/docs/category/schemas) detail the various JSON objects that Doc Detective expects for [configs](https://doc-detective.com/docs/references/schemas/config.html), [test specifications](https://doc-detective.com/docs/references/schemas/specification.html), [tests](https://doc-detective.com/docs/references/schemas/test), actions, and more. Open [typeKeys](https://doc-detective.com/docs/references/schemas/typeKeys.html)--or any other schema--and you'll find two sections: **Fields** and **Examples**.
 
-  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/"})
-  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/config.html"})
-  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/specification.html"})
-  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/reference/schemas/test.html"})
-  [comment]: # (step {"action":"goTo", "url":"https://doc-detective.com/reference/schemas/typeKeys.html"})
-  [comment]: # (step {"action":"find", "selector":"h2#description", "matchText":"Description"})
+  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/docs/category/schemas"})
+  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/docs/references/schemas/config.html"})
+  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/docs/references/schemas/specification.html"})
+  [comment]: # (step {"action":"checkLink", "url":"https://doc-detective.com/docs/references/schemas/test.html"})
+  [comment]: # (step {"action":"goTo", "url":"https://doc-detective.com/docs/references/schemas/typeKeys.html"})
   [comment]: # (step {"action":"find", "selector":"h2#fields", "matchText":"Fields"})
   [comment]: # (step {"action":"find", "selector":"h2#examples", "matchText":"Examples"})
 

package/src/checkDependencies.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const fs = require("fs");
+const readline = require("readline");
+
+// Check if package.json exists, and if it's for doc-detective
+if (fs.existsSync(path.resolve(process.cwd(), "package.json"))) {
+  try {
+    const json = JSON.parse(
+      fs.readFileSync(path.resolve(process.cwd(), "package.json"))
+    );
+    if (json.name === "doc-detective") {
+      // Check if dependencies are installed
+      checkDependencies();
+    }
+  } catch (error) {
+    console.error(`Failed to parse package.json: ${error.message}`);
+  }
+}
+
+// Check if dependencies are installed
+function checkDependencies() {
+  if (!fs.existsSync(path.resolve(process.cwd(), "node_modules"))) {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    // Handle SIGINT (Ctrl+C)
+    rl.on('SIGINT', () => {
+      console.log('\nOperation cancelled by user');
+      rl.close();
+      process.exit(0);
+    });
+
+    rl.question(
+      "It looks like you haven't installed the local dependencies yet. Would you like to install them now? (yes/no): ",
+      (answer) => {
+        const normalizedAnswer = answer.toLowerCase().trim();
+        if (normalizedAnswer === "yes" || normalizedAnswer === "y") {
+          console.log("Installing dependencies. This may take a few minutes.");
+          const { spawn } = require("child_process");
+          const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+          const install = spawn(npmCmd, ["install"], { 
+            stdio: "inherit",
+            shell: true 
+          });
+
+          // Set timeout
+          const timeout = setTimeout(() => {
+            console.error('Installation timed out after 5 minutes');
+            install.kill();
+            rl.close();
+          }, 5 * 60 * 1000);
+
+          install.on("close", (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+              console.error(
+                `Failed to install dependencies (exit code ${code}). Try running 'npm install' manually and check for errors.`
+              );
+              process.exit(1);
+            } else {
+              console.log("Dependencies installed successfully.");
+            }
+            rl.close();
+          });
+
+          install.on("error", (error) => {
+            clearTimeout(timeout);
+            console.error(`Failed to start 'npm install': ${error.message}`);
+            rl.close();
+            process.exit(1);
+          });
+        } else {
+          console.log("Dependencies not installed. Please run 'npm install' manually before proceeding.");
+          rl.close();
+          process.exit(1);
+        }
+      }
+    );
+  }
+}