docs: improve debugging documentation (#1636) (#1637)

DEBUGGING.md

@@ -0,0 +1,95 @@
+# Debugging at Orval
+
+There are several methods available for debugging the Orval codebase.
+
+## Running the Development Environment
+
+The first step when working with the project is to set up the development environment. After following the setup instructions in the [CONTRIBUTING.md](./CONTRIBUTING.md) file, you can use the default command `yarn dev` to run the codebase locally. This command is part of the `turbo dev` process and will run the sample project located at [react-query/basic](./samples/react-query/basic/). You can use this sample as a starting point to debug the output generated by the project.
+
+If you'd like to try debugging a different sample, feel free to update the `generate-api` script in the [package.json](./packages/orval/package.json) file to reference a different sample or modify the existing `react-query/basic` sample as needed.
+
+Once your environment is set up, the only remaining step is to configure your IDE to allow for breakpoint debugging. This will enable you to step through the code and inspect specific areas of interest.
+
+Below is an example configuration for Visual Studio Code that you can add to your `launch.json` file:
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Run Dev Server",
+  "runtimeExecutable": "yarn",
+  "args": ["dev"],
+  "skipFiles": ["<node_internals>/**"],
+  "console": "integratedTerminal",
+  "internalConsoleOptions": "neverOpen",
+  "env": {
+    "PATH": "${workspaceFolder}/node_modules/.bin:${env:PATH}" // This ensures VS Code references the project's local packages
+  },
+  "cwd": "${workspaceFolder}"
+}
+```
+
+## Debugging with Tests
+
+Another approach to debugging is by writing and running tests. This is especially useful if you want to isolate specific pieces of code and evaluate their performance without delving into the entire codebase.
+
+Testing can be more complex than running the development environment, as it requires a thorough understanding of the interfaces and functions you aim to test. However, once familiar with the codebase, this approach becomes highly effective for targeted debugging.
+
+To implement this, create a test file adjacent to the code file you want to test. For example, if you're working on [operation.ts](./packages/core/src/getters/operation.ts), you would create a corresponding test file named [operation.test.ts](./packages/core/src/getters/operation.test.ts).
+
+Benefits of this approach:
+
+1. It improves the overall codebase by adding test coverage.
+2. It allows you to test isolated pieces of the code, making the debugging process more predictable.
+
+To run these tests in your IDE, you can use the following configuration in Visual Studio Code:
+
+```json
+{
+  "type": "node",
+  "request": "launch",
+  "name": "Debug Current Test File",
+  "runtimeExecutable": "yarn",
+  "args": [
+    "test",
+    "${file}" // Refers to the currently open file in the editor
+  ],
+  "skipFiles": ["<node_internals>/**"],
+  "console": "integratedTerminal",
+  "internalConsoleOptions": "neverOpen",
+  "env": {
+    "PATH": "${workspaceFolder}/node_modules/.bin:${env:PATH}" // This ensures VS Code references the project's local packages
+  },
+  "cwd": "${workspaceFolder}"
+}
+```
+
+**Note for Windows users:** You may need to adjust the `cwd` path to include the specific package directory, such as `"${workspaceFolder}/packages/core"`.
+
+## Troubleshooting
+
+### 1. Undefined function when running the `generate` command?
+
+Due to the monorepo structure, debugging the entire flow at once can be challenging. To simplify the process, try mocking some of the packages or breaking the flow into smaller, more manageable parts.
+
+You can also extract the parameters passed to the function, create fixtures with those values, and import them as JSON files to test changes in isolation.
+
+### 2. Missing dependencies like TSC or Vitest?
+
+This error occurs when your IDE is unable to locate the necessary binaries in `node_modules`. It usually means you need to configure your IDE to reference the local `node_modules` folder. Use the following environment variable to resolve this issue:
+
+```json
+"env": {
+  "PATH": "${workspaceFolder}/node_modules/.bin:${env:PATH}"
+}
+```
+
+### 3. Tests not found in the launcher?
+
+This issue often arises in a monorepo structure because the test runner cannot locate the correct path. To fix this, specify the package path in the `cwd` field as shown below:
+
+```json
+"cwd": "${workspaceFolder}/packages/{package-to-reference}"
+```
+
+This is especially common on Windows, where path handling requires more explicit configuration.