docs: clarify test file discovery prioritisation behavior

[umxr]

The existing documentation stated that test files "can either be" in the root directory or test folder, which I interpreted as both could be used simultaneously. However, the actual behavior prioritizes root files and completely ignores the test directory when both exist.

Solution

This PR clarifies the test file discovery behavior by adding detailed explanations of the priority order and providing clear guidance on how to handle multiple test locations, preventing others from experiencing the same confusion I encountered.

Key Changes

1. Enhanced "Order of Operations" Section

• Before: Vague statement that files "can either be" in root or test directory
• After: Clear priority order with bullet points explaining the discovery sequence
• Added: Important warning box about the behavior when both exist
• Added: Explicit solutions (move to test directory or use --files flag)

2. Updated "Test Directory" Configuration Section

• Added: Note explaining when the test directory is actually used
• Added: Cross-reference to "Order of Operations" for complete details

3. Enhanced CLI Documentation

• Improved: --files flag documentation with practical example
• Added: Context about when this approach is useful for multiple test locations

Detailed Changes

Order of Operations Section

- 3. Finds `.test-d.ts` and `.test-d.tsx` files, which can either be in the project's root directory, a [specific folder](#test-directory) (by default `/[project-root]/test-d`), or specified individually [programatically](#testfiles) or via [the CLI](#via-the-cli). Fails if no test files are found.

+ 3. Finds `.test-d.ts` and `.test-d.tsx` files using the following priority order:
+    - **First**: Looks for test files in the project's root directory (e.g., `index.test-d.ts`)
+    - **Second**: Only if no root test files are found, looks in the [test directory](#test-directory) (by default `/[project-root]/test-d`) for any `.ts` or `.tsx` files
+    - **Alternative**: Test files can be specified individually [programatically](#testfiles) or via [the CLI](#via-the-cli)
+    
+    **Important**: If you have both a root-level test file (like `index.test-d.ts`) and a test directory (like `test-d/`), only the root-level file will be executed. The test directory will be ignored. To use both, either move all tests to the test directory or use the `--files` flag to specify all test files explicitly.
+    
+    Fails if no test files are found.

Test Directory Section

  Now you can put all your test files in the `my-test-dir` directory.

+ **Note**: The test directory is only used when no test files are found in the project root. If you have both root-level test files (like `index.test-d.ts`) and a test directory, only the root files will be executed. See [Order of Operations](#order-of-operations) for more details.

CLI Documentation

  An array of test files with their path. Same as [`testFiles`](#testfiles).

+ This is particularly useful when you need to run tests from multiple locations (e.g., both root-level and test directory files):
+ 
+ ```bash
+ tsd --files "index.test-d.ts" --files "test-d/**/*.test-d.ts"
+ ```

My Workaround

After discovering this behavior, I solved my issue by using the --files flag to explicitly specify all test locations:

tsd --files "index.test-d.ts" --files "test-d/**/*.test-d.ts"

This allowed me to run both my root-level test file and all tests in my test directory as I originally intended.

Benefits

• Eliminates confusion: Others won't have to debug why their test directory is being ignored
• Prevents silent failures: Clear warning about test directory being ignored when root files exist
• Provides solutions: Two practical workarounds for mixed test locations
• Improves discoverability: Cross-references help users find related information
• Better UX: Reduces debugging time when tests don't run as expected

Validation

• Verified all internal links work correctly
• Confirmed markdown formatting renders properly
• Checked examples are accurate and executable
• Ensured cross-references are consistent
• Validated that the documented behavior matches the actual code implementation

Impact

This documentation improvement addresses the exact confusion I experienced and will help other TypeScript library authors avoid the same issue. The changes maintain backward compatibility while significantly improving the user experience through better documentation clarity.