docs: Document test detection enhancements and source location tracking

fern/pages/contribute/repos/doc-detective-common.md

@@ -7,3 +7,46 @@ title: doc-detective-common
 The source code lives in the [`doc-detective`](https://github.com/doc-detective/doc-detective) monorepo under `src/common/`, but the package is still published independently to NPM.
 
 This package doesn't depend on any other Doc Detective packages.
+
+## Public exports
+
+The package exports the following types and utilities:
+
+### Types
+
+- `Specification`: TypeScript type for test specifications
+- `Test`: TypeScript type for test objects
+- `Step`: TypeScript type for step objects
+- `Context`: TypeScript type for context objects
+- `Config`: TypeScript type for configuration objects
+- `Report`: TypeScript type for report objects
+- `FileType`: TypeScript type for file type definitions
+
+### Utilities
+
+- `schemas`: All JSON schemas for validation
+- `validate()`: Validate objects against Doc Detective schemas
+- `detectTests()`: Detect tests from documentation content
+- `defaultFileTypes`: Default file type definitions for Markdown, HTML, AsciiDoc, and DITA
+
+### Example usage
+
+```javascript
+import {
+  detectTests,
+  defaultFileTypes,
+  validate
+} from "doc-detective-common";
+
+// Detect tests from Markdown content
+const tests = await detectTests({
+  content: "Click **Submit** to continue.",
+  fileType: defaultFileTypes.markdown
+});
+
+// Validate a test specification
+const result = validate({
+  schemaKey: "spec_v3",
+  object: mySpec
+});
+```

fern/pages/docs/tests/detected.mdx

@@ -3,7 +3,7 @@ title: Detected tests
 description: Automatically generate tests based on your documentation source files.
 ---
 
-Doc Detective can automatically generate tests based on your documentation source files and your `fileTypes` configuration. Detected tests are useful for large, complex test suites that you want to keep in sync with your documentation. Test detection works by setting `detectSteps` to `true` and defining markup patterns and associated actions in the `fileTypes.markup` array in your [config](/reference/schemas/config), which Doc Detective uses to extract steps from your doc source files. You can define multiple test patterns in your config to extract different types of tests from your documentation.
+Doc Detective can automatically generate tests based on your documentation source files and your `fileTypes` configuration. Detected tests are useful for large, complex test suites that you want to keep in sync with your documentation. Test detection is enabled by default (`detectSteps: true`) and uses markup patterns and associated actions defined in the `fileTypes.markup` array in your [config](/reference/schemas/config) to extract steps from your doc source files. You can define multiple test patterns in your config to extract different types of tests from your documentation.
 
 Detected tests are useful for keeping your tests in sync with your documentation. When you update your documentation, Doc Detective automatically updates the tests based on the new content. Detected tests are generated automatically. You can't edit detected tests directly, but you can update your config or documentation source files to change the tests.
 
@@ -20,6 +20,35 @@ Detected tests provide several advantages:
 
 Combine detected tests with [inline tests](./inline-tests) for comprehensive test coverage with minimal manual effort.
 
+## Source location tracking
+
+Detected steps include source location metadata that identifies where each step was found in your documentation. This information is useful for debugging failed tests and understanding which parts of your documentation triggered specific test steps.
+
+Each detected step includes a `location` object with:
+
+- **line**: The 1-indexed line number where the step was detected
+- **startIndex**: The 0-indexed character offset where the step begins
+- **endIndex**: The 0-indexed character offset where the step ends
+
+For example, a detected step might include:
+
+```json
+{
+  "click": "Search",
+  "location": {
+    "line": 5,
+    "startIndex": 42,
+    "endIndex": 58
+  }
+}
+```
+
+<Note>
+
+The `location` property is read-only system metadata. You can't set it manually in your test specifications.
+
+</Note>
+
 ## Default markup patterns
 
 Doc Detective includes default markup patterns for Markdown and DITA files. For comprehensive information about each input format and their patterns, see [Input formats](/docs/input-formats/overview).

fern/pages/reference/schemas/common.md

@@ -19,6 +19,7 @@ unsafe | boolean | Optional. Whether or not the step may be unsafe. Unsafe steps
 outputs | object(Outputs (step)) | Optional. Outputs from step processes and user-defined expressions. Use the `outputs` object to reference outputs in subsequent steps. If a user-defined output matches the key for a step-defined output, the user-defined output takes precedence. | ``{}``
 variables | object(Variables (step)) | Optional. Environment variables to set from user-defined expressions. | ``{}``
 breakpoint | boolean | Optional. Whether or not this step should act as a breakpoint when debugging is enabled. When `true`, execution will pause at this step when debug mode is enabled. | `false`
+location | object([Source Location](/reference/schemas/source-location)) | ReadOnly. Source location where this step was detected in the original file. This is system-populated metadata for [detected tests](/docs/tests/detected) and should not be set manually. |
 
 ## Examples
 

fern/pages/reference/schemas/source-location.md

@@ -0,0 +1,35 @@
+---
+title: "Source Location"
+---
+
+Source location metadata for [detected tests](/docs/tests/detected). This object identifies where a step was detected in a documentation source file.
+
+## Referenced In
+
+- [Common](/reference/schemas/common)
+
+## Fields
+
+Field | Type | Description | Default
+:-- | :-- | :-- | :--
+line | integer | Required. 1-indexed line number in the source file where the step was detected. Minimum: 1 |
+startIndex | integer | Required. 0-indexed character offset from the start of the source file where the step begins. Minimum: 0 |
+endIndex | integer | Required. 0-indexed character offset from the start of the source file where the step ends (exclusive). Minimum: 0 |
+
+## Examples
+
+```json
+{
+  "line": 5,
+  "startIndex": 42,
+  "endIndex": 58
+}
+```
+
+```json
+{
+  "line": 12,
+  "startIndex": 156,
+  "endIndex": 203
+}
+```