build: enable breakpoints in source files (angular#64220)

This commit revamps the debugging setup and enabling developers to set breakpoints directly in the source TypeScript files.

Key changes include:
- Updated `launch.json` with source map path overrides to correctly map compiled output back to the original source code.
- Switched from `external` to `linked` sourcemaps in the Bazel build configuration for better debugging support.
- Consolidated the recommended VSCode settings into the main `launch.json` and `tasks.json`, removing the separate `recommended-*.json` files.
- Updated the debugging documentation to reflect the new, simplified workflow.

These changes significantly improve the developer experience for contributors working on the language service, making it much easier to debug and troubleshoot issues.

This applies to both the framework packages and vscode-ng-langugage-service.

PR Close angular#64220

Author: alan-agius4

.vscode/README.md

@@ -8,8 +8,6 @@ To use the recommended configurations follow the steps below:
 
 - install the recommended extensions in `.vscode/extensions.json`
 - copy (or link) `.vscode/recommended-settings.json` to `.vscode/settings.json`
-- copy (or link) `.vscode/recommended-launch.json` to `.vscode/launch.json`
-- copy (or link) `.vscode/recommended-tasks.json` to `.vscode/tasks.json`
 - restart the editor
 
 If you already have your custom workspace settings, you should instead manually merge the file contents.

.vscode/launch.json

@@ -11,11 +11,7 @@
         "--disable-extensions",
         "--extensionDevelopmentPath=${workspaceFolder}/vscode-ng-language-service"
       ],
-      "outFiles": [
-        "${workspaceFolder}/dist/bin/vscode-ng-language-service/client/index.js",
-        "${workspaceFolder}/dist/bin/vscode-ng-language-service/server/index.js"
-      ],
-      "preLaunchTask": "vsce: watch bundles"
+      "preLaunchTask": "VSCE: watch bundles"
     },
     {
       "type": "extensionHost",
@@ -26,23 +22,63 @@
         "--disable-extensions",
         "--extensionDevelopmentPath=${workspaceFolder}/dist/bin/vscode-ng-language-service/npm/vscode-ng-language-service/vsix_sandbox"
       ],
-      "sourceMaps": false,
-      "preLaunchTask": "vsce: package"
+      "preLaunchTask": "VSCE: package"
     },
     {
+      "name": "VSCE: Attach to Server",
       "type": "node",
       "request": "attach",
-      "name": "VSCE: Attach to Server",
       "port": 6009,
       "restart": true,
+      "sourceMaps": true,
+      "skipFiles": ["<node_internals>/**"],
+      "sourceMapPathOverrides": {
+        "?:*/bin/*": "${workspaceFolder}/*"
+      },
+      "resolveSourceMapLocations": ["!**/node_modules/**"]
+    },
+    {
+      "name": "DEBUG: Attach to bazel test",
+      "type": "node",
+      "request": "attach",
+      "port": 9229,
+      "restart": true,
+      "timeout": 600000,
+      "sourceMaps": true,
       "skipFiles": ["<node_internals>/**"],
-      "outFiles": ["${workspaceFolder}/dist/bin/vscode-ng-language-service/server/index.js"]
+      "sourceMapPathOverrides": {
+        "?:*/bin/*": "${workspaceFolder}/*"
+      },
+      "resolveSourceMapLocations": ["!**/node_modules/**"]
+    },
+    {
+      "name": "DEBUG: Run bazel test (Custom Target)",
+      "type": "node",
+      "request": "launch",
+      "restart": true,
+      "timeout": 600000,
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["bazel", "test", "${input:bazelTarget}", "--config=debug"],
+      "console": "integratedTerminal",
+      "cwd": "${workspaceFolder}"
     }
   ],
   "compounds": [
     {
-      "name": "VSCE: Dev Client + Server",
+      "name": "VSCE: Dev Client + Attach to Server",
       "configurations": ["VSCE: Launch Dev Client", "VSCE: Attach to Server"]
+    },
+    {
+      "name": "DEBUG: Run bazel test (Custom Target) + Attach",
+      "configurations": ["DEBUG: Attach to bazel test", "DEBUG: Run bazel test (Custom Target)"]
+    }
+  ],
+  "inputs": [
+    {
+      "id": "bazelTarget",
+      "type": "promptString",
+      "description": "Enter the Bazel test target (e.g., //path/to/my:unit_test)",
+      "default": "//packages/..."
     }
   ]
 }

.vscode/recommended-launch.json

@@ -21,7 +21,5 @@
     ".history": true
   },
   "git.ignoreLimitWarning": true,
-  "gitlens.advanced.blame.customArguments": [
-    "--ignore-revs-file .git-blame-ignore-revs"
-  ]
+  "gitlens.advanced.blame.customArguments": ["--ignore-revs-file .git-blame-ignore-revs"]
 }

.vscode/recommended-settings.json

@@ -3,7 +3,7 @@
   "tasks": [
     {
       "type": "shell",
-      "label": "vsce: watch bundles",
+      "label": "VSCE: watch bundles",
       "command": "pnpm --filter=ng-template run watch",
       "isBackground": true,
       "group": {
@@ -25,7 +25,7 @@
     },
     {
       "type": "shell",
-      "label": "vsce: package",
+      "label": "VSCE: package",
       "command": "pnpm --filter=ng-template run package"
     }
   ]

.vscode/recommended-tasks.json

@@ -97,22 +97,28 @@ First time setup:
 - Add the following to the `configurations` array:
 
 ```json
-    {
-      "type": "node",
-      "request": "attach",
-      "name": "Attach to Remote",
-      "port": 9229
-    }
+{
+  "name": "Attach to Process",
+  "type": "node",
+  "request": "attach",
+  "port": 9229,
+  "restart": true,
+  "timeout": 600000,
+  "sourceMaps": true,
+  "skipFiles": ["<node_internals>/**"],
+  "sourceMapPathOverrides": {
+    "?:*/bin/*": "${workspaceFolder}/*"
+  },
+  "resolveSourceMapLocations": ["!**/node_modules/**"]
+}
 ```
 
-**Setting breakpoints directly in your code files may not work in VSCode**. This is because the
-files you're actually debugging are built files that exist in a `./private/...` folder.
-The easiest way to debug a test for now is to add a `debugger` statement in the code
-and launch the bazel corresponding test (`pnpm bazel test <target> --config=debug`).
+The easiest way to debug a test for now is to add a `debugger` statement or add a break point
+in the code and launch the bazel corresponding test (`pnpm bazel test <target> --config=debug`).
 
 Bazel will wait on a connection. Go to the debug view (by clicking on the sidebar or
 Apple+Shift+D on Mac) and click on the green play icon next to the configuration name
-(ie `Attach to Remote`).
+(ie `Attach to Process`).
 
 ### Debugging a Karma Test
 

.vscode/tasks.json

@@ -26,7 +26,7 @@ expand_template_rule(
         "0.0.0-PLACEHOLDER": "{{BUILD_SCM_VERSION}}",
     },
     substitutions = {
-        "../dist/bin/vscode-ng-language-service/client/index": "./index",
+        "../dist/bin/vscode-ng-language-service/client/src/extension.js": "./index",
     },
     template = "package.json",
 )

contributing-docs/building-with-bazel.md

@@ -29,7 +29,7 @@ esbuild(
     # Do not enable minification. It seems to break the extension on Windows (with WSL). See #1198.
     minify = False,
     platform = "node",
-    sourcemap = "external",
+    sourcemap = "linked",
     visibility = ["//vscode-ng-language-service:__pkg__"],
     deps = [
         "//:node_modules/source-map-support",

vscode-ng-language-service/BUILD.bazel

@@ -313,7 +313,7 @@ export class AngularLanguageClient implements vscode.Disposable {
             // do not lazily evaluate the code so all breakpoints are respected
             '--nolazy',
             // If debugging port is changed, update .vscode/launch.json as well
-            '--inspect=6009',
+            '--inspect-brk=6009',
           ],
           env: {
             NG_DEBUG: true,