Merge branch 'topic/sourcemap' into 'master'

Package a sourcemap file for the Ada extension

Closes #1282

See merge request eng/ide/ada_language_server!1479

Author: eliericha

doc/HACKING.md

@@ -75,6 +75,40 @@ and run
 
 On Mac OX X use [atos](https://www.unix.com/man-page/osx/1/atos/) instead.
 
+## Getting symbolic backtrace for TypeScript
+
+The Ada & SPARK extension for Visual Studio Code is published as minified
+JavaScript code. For that reason backtraces reported are not easily readable
+by humans. To alleviate that, the published .vsix includes a source map file
+at `out/src/extension.js.map`.
+
+To resolve a backtrace to the original TypeScript source locations:
+
+1. Unzip the .vsix
+
+2. Copy the backtrace into a plain text file *while preserving the error message
+on the first line*, for example:
+
+    ```
+    2024-01-11 10:11:54.191 [Ada Extension] ERROR    Error while starting Ada extension...
+        at Gu (/home/XXXXXXX/.vscode/extensions/adacore.ada-24.0.3/out/src/extension.js:75:5911)
+        at oS (/home/XXXXXXX/.vscode/extensions/adacore.ada-24.0.3/out/src/extension.js:75:6057)
+        at w$ (/home/XXXXXXX/.vscode/extensions/adacore.ada-24.0.3/out/src/extension.js:85:2292)
+        at b$ (/home/XXXXXXX/.vscode/extensions/adacore.ada-24.0.3/out/src/extension.js:85:2154)
+        ...
+    ```
+
+3. Run the following command to obtain source locations:
+
+   ```
+   $ npx stacktracify out/src/extension.js.map -f trace.txt
+   2024-01-11 10:11:54.191 [Ada Extension] ERROR    Error while starting Ada extension...
+       at [unknown] (../../src/helpers.ts:150:56)
+       at getEvaluatedCustomEnv (../../src/helpers.ts:186:22)
+       at assertSupportedEnvironments (../../src/extension.ts:128:4)
+       at activateExtension (../../src/extension.ts:118:14)
+   ```
+
 ### Writing tests
 
 To write a functional test for Ada Language Server:

integration/vscode/ada/.vscodeignore

@@ -1,3 +1,4 @@
+# This file contains patterns to exclude from the packaging into a .vsix
 .vscode-test/
 advanced/
 node_modules/
@@ -10,5 +11,6 @@ test/
 debug.code-workspace
 run_grammar_tests.sh
 tsconfig.json
-**/*.map
 **/*.ts
+**/*.ts.map
+xfail.yaml

integration/vscode/ada/package.json

@@ -875,14 +875,15 @@
     },
     "scripts": {
         "check-licenses": "npx license-checker-rseidelsohn --summary --onlyAllow \"0BSD;Apache-2.0;BSD-2-Clause;BSD-3-Clause;BlueOak-1.0.0;CC0-1.0;GPL-3.0;GPL-3.0-or-later;ISC;MIT;Python-2.0;Zlib\"",
-        "vscode:prepublish": "npm run esbuild-base -- --minify",
+        "vscode:prepublish": "npm run esbuild-base -- --minify --sourcemap",
         "esbuild-base": "esbuild ./src/extension.ts --bundle --outfile=out/src/extension.js --external:vscode --format=cjs --platform=node",
         "compile": "node ./node_modules/typescript/bin/tsc",
         "watch": "node ./node_modules/typescript/bin/tsc -watch",
         "pretest": "npm run compile",
         "lint": "eslint \"./src/**/*.{js,ts,tsx}\" --quiet --fix",
         "cilint": "eslint \"./src/**/*.{js,ts,tsx}\"",
-        "test": "node ./out/test/runTest.js"
+        "test": "node ./out/test/runTest.js",
+        "resolve-backtrace": "npx stacktracify"
     },
     "dependencies": {
         "@types/command-exists": "1.2.0",