Add note about mutually exclusive properties in schema reference

Co-authored-by: hawkeyexl <[email protected]>

Author: Copilot

.scripts/buildSchemaReferencesV3.js

@@ -36,9 +36,23 @@ async function main() {
     let fields = [
       "## Fields",
       "",
+    ];
+    
+    // Add warning about mutually exclusive properties if the schema has top-level anyOf/oneOf
+    if (schema.anyOf || schema.oneOf) {
+      const mutuallyExclusiveProps = extractMutuallyExclusiveActionProperties(schema);
+      if (mutuallyExclusiveProps.length > 0) {
+        fields.push("> **Note:** The following action properties are mutually exclusive. You can only use one of these in a single step:");
+        fields.push("> ");
+        fields.push("> `" + mutuallyExclusiveProps.join("`, `") + "`");
+        fields.push("");
+      }
+    }
+    
+    fields = fields.concat([
       "Field | Type | Description | Default",
       ":-- | :-- | :-- | :--",
-    ];
+    ]);
 
     // Handle top-level anyOf/oneOf schemas (like screenshot which can be string, object, or boolean)
     if (schema.anyOf || schema.oneOf) {
@@ -756,4 +770,70 @@ function getArraySubTypes(property, depth) {
   }
 
   return subTypes;
+}
+
+/**
+ * Extract action property names from the schema that are mutually exclusive
+ * (typically at the top level of an anyOf)
+ */
+function extractMutuallyExclusiveActionProperties(schema) {
+  const actionProps = [];
+  
+  // Check if the schema has a top-level anyOf or oneOf
+  if (!schema.anyOf && !schema.oneOf) {
+    return actionProps;
+  }
+  
+  const variants = schema.anyOf || schema.oneOf;
+  
+  // For each variant, find the action property (usually in required array)
+  for (const variant of variants) {
+    // Handle typical allOf structure in step schema 
+    // where common properties are in one block and action-specific in another
+    if (variant.allOf) {
+      for (const allOfItem of variant.allOf) {
+        if (allOfItem.required && allOfItem.required.length > 0) {
+          // Find the action property that's required
+          for (const requiredProp of allOfItem.required) {
+            // Skip common properties that can be used with any action
+            if (['stepId', 'description', 'outputs', 'variables'].includes(requiredProp)) {
+              continue;
+            }
+            if (!actionProps.includes(requiredProp)) {
+              actionProps.push(requiredProp);
+            }
+          }
+        }
+        
+        // Also check the properties directly if they're specific action types
+        if (allOfItem.properties) {
+          for (const propName of Object.keys(allOfItem.properties)) {
+            // Skip common properties that can be used with any action
+            if (['stepId', 'description', 'outputs', 'variables'].includes(propName)) {
+              continue;
+            }
+            // Add property if it seems to be an action (has $schema or title)
+            const prop = allOfItem.properties[propName];
+            if ((prop.$schema || prop.title) && !actionProps.includes(propName)) {
+              actionProps.push(propName);
+            }
+          }
+        }
+      }
+    }
+    // Handle direct required properties in the variant
+    else if (variant.required) {
+      for (const requiredProp of variant.required) {
+        // Skip common properties
+        if (['stepId', 'description', 'outputs', 'variables'].includes(requiredProp)) {
+          continue;
+        }
+        if (!actionProps.includes(requiredProp)) {
+          actionProps.push(requiredProp);
+        }
+      }
+    }
+  }
+  
+  return actionProps;
 }

docs/references/schemas/checkLink.md

@@ -5,6 +5,10 @@
 
 ## Fields
 
+> **Note:** The following action properties are mutually exclusive. You can only use one of these in a single step:
+> 
+> `url`
+
 Field | Type | Description | Default
 :-- | :-- | :-- | :--
 checkLink | string | Check if an HTTP or HTTPS URL returns an acceptable status code from a GET request. | 

docs/references/schemas/config.md

@@ -8,6 +8,7 @@ Configuration options for Doc Detective operations.
 Field | Type | Description | Default
 :-- | :-- | :-- | :--
 configId | string | Optional. Identifier for the configuration. | 
+configPath | string | ReadOnly. Path to the configuration file. | 
 input | string | Optional. Path(s) to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | 
 input | array of string | Optional. Path(s) to test specifications and documentation source files. May be paths to specific files or to directories to scan for files. | 
 output | string | Optional. Path of the directory in which to store the output of Doc Detective commands. If a file path is specified, Doc Detective attempts to honor the file name specified, but file path behavior is controlled by the configured reporters. | `.`
@@ -28,6 +29,10 @@ integrations.openApi | array of unknown | Optional. No description provided. |
 telemetry | object | Optional. Options around sending telemetry for Doc Detective usage. | ``{"send":true}``
 telemetry.send | boolean | Required. If `true`, sends Doc Detective telemetry. | `true`
 telemetry.userId | string | Optional. Identifier for the organization, group, or individual running Doc Detective. | 
+environment | object | ReadOnly. Environment information for the system running Doc Detective. | 
+environment.workingDirectory | string | Optional. The current working directory of the process running Doc Detective. | 
+environment.platform | string | Required. The operating system type running Doc Detective.<br/><br/>Accepted values: `linux`, `mac`, `windows` | 
+environment.arch | string | Optional. The processor architecture of the system running Doc Detective.<br/><br/>Accepted values: `arm32`, `arm64`, `x32`, `x64` | 
 
 ## Examples
 
@@ -111,3 +116,12 @@ telemetry.userId | string | Optional. Identifier for the organization, group, or
   ]
 }
 ```
+
+```json
+{
+  "environment": {
+    "platform": "windows",
+    "arch": "x64"
+  }
+}
+```

docs/references/schemas/goTo.md

@@ -5,6 +5,10 @@
 
 ## Fields
 
+> **Note:** The following action properties are mutually exclusive. You can only use one of these in a single step:
+> 
+> `url`
+
 Field | Type | Description | Default
 :-- | :-- | :-- | :--
 goTo | string | Navigate to an HTTP or HTTPS URL. Can be a full URL or a path. If a path is provided, navigates relative to the current URL, if any. | 

docs/references/schemas/runCode.md

@@ -5,6 +5,10 @@ Assemble and run code.
 
 ## Fields
 
+> **Note:** The following action properties are mutually exclusive. You can only use one of these in a single step:
+> 
+> `code`, `language`
+
 Field | Type | Description | Default
 :-- | :-- | :-- | :--
 language | string | Required. Language of the code to run.<br/><br/>Accepted values: `python`, `bash`, `javascript` | 

docs/references/schemas/runShell.md

@@ -5,6 +5,10 @@ Perform a native shell command.
 
 ## Fields
 
+> **Note:** The following action properties are mutually exclusive. You can only use one of these in a single step:
+> 
+> `command`
+
 Field | Type | Description | Default
 :-- | :-- | :-- | :--
 runShell | string | No description provided. | 

docs/references/schemas/specification.md

@@ -9,6 +9,7 @@ Field | Type | Description | Default
 :-- | :-- | :-- | :--
 specId | string | Optional. Unique identifier for the test specification. | 
 description | string | Optional. Description of the test specification. | 
+specPath | string | Optional. Path to the test specification. | 
 contentPath | string | Optional. Path to the content that the specification is associated with. | 
 runOn | array of object | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | 
 openApi | array of unknown | Optional. No description provided. | 

docs/references/schemas/step.md

@@ -5,6 +5,10 @@ A step in a test.
 
 ## Fields
 
+> **Note:** The following action properties are mutually exclusive. You can only use one of these in a single step:
+> 
+> `checkLink`, `click`, `find`, `goTo`, `httpRequest`, `runShell`, `runCode`, `type`, `screenshot`, `record`, `stopRecord`, `loadVariables`, `wait`
+
 Field | Type | Description | Default
 :-- | :-- | :-- | :--
 stepId | string | Optional. ID of the step. | 

docs/references/schemas/test.md

@@ -5,6 +5,10 @@ A Doc Detective test.
 
 ## Fields
 
+> **Note:** The following action properties are mutually exclusive. You can only use one of these in a single step:
+> 
+> `steps`, `contexts`
+
 Field | Type | Description | Default
 :-- | :-- | :-- | :--
 testId | string | Optional. Unique identifier for the test. | 
@@ -15,7 +19,12 @@ runOn | array of object | Optional. Contexts to run the test in. Overrides conte
 openApi | array of unknown | Optional. No description provided. | 
 before | string | Optional. Path to a test specification to perform before this test, while maintaining this test's context. Useful for setting up testing environments. Only the `steps` property is used from the first test in the setup spec. | 
 after | string | Optional. Path to a test specification to perform after this test, while maintaining this test's context. Useful for cleaning up testing environments. Only the `steps` property is used from the first test in the cleanup spec. | 
-steps | array of object | Required. Steps to perform as part of the test. Performed in the sequence defined. If one or more actions fail, the test fails. By default, if a step fails, the test stops and the remaining steps are not executed. | 
+steps | array of object | Optional. Steps to perform as part of the test. Performed in the sequence defined. If one or more actions fail, the test fails. By default, if a step fails, the test stops and the remaining steps are not executed. | 
+contexts | array of object | ReadOnly. Resolved contexts to run the test in. This is a resolved version of the `runOn` property. It is not user-defined and should not be used in test specifications. | 
+contexts[].platform | string | Optional. Platform to run the test on. This is a resolved version of the `platforms` property. | 
+contexts[].browser | object | Optional. Browser configuration. | 
+contexts[].openApi | array of unknown | Optional. No description provided. | 
+contexts[].steps | array of <br/>one of:<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown<br/>- unknown | Optional. Steps to perform as part of the test. Performed in the sequence defined. If one or more actions fail, the test fails. By default, if a step fails, the test stops and the remaining steps are not executed. | 
 
 ## Examples
 

docs/references/schemas/typeKeys.md

@@ -5,6 +5,10 @@ Type keys. To type special keys, begin and end the string with `$` and use the s
 
 ## Fields
 
+> **Note:** The following action properties are mutually exclusive. You can only use one of these in a single step:
+> 
+> `keys`
+
 Field | Type | Description | Default
 :-- | :-- | :-- | :--
 typeKeys | string | No description provided. |