chore: Add typescript to type check JS Interface via JSDoc (#2611)

This PR adds `typescript` to the repo to type-check the JS interface of
Sentry CLI. I decided to build on top of the already existing JSDoc type
annotations but actually enforce them by running TS.

This also surfaced an incorrect type annotation which I fixed as well,
along with adding some minor necessary annotations.

Author: Lms24

.github/workflows/test_node.yml

@@ -8,6 +8,22 @@ on:
         value: ${{ jobs.test_node.result }}
 
 jobs:
+  type_check:
+    name: Type Check
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 4.2.2
+
+      - name: Use Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # 4.4.0
+        with:
+          node-version-file: package.json
+
+      # We need to skip the fallback download because downloading will fail on release branches because the new version isn't available yet.
+      - run: SENTRYCLI_SKIP_DOWNLOAD=1 npm install
+
+      - run: npm run check:types
+
   test_node:
     strategy:
       fail-fast: false

js/helper.js

@@ -186,6 +186,7 @@ function mockBinaryPath(mockPath) {
  * @typedef {object} OptionSchema
  * @prop {string} param The flag of the command line option including dashes.
  * @prop {OptionType} type The value type of the command line option.
+ * @prop {string} [invertedParam] The flag of the command line option including dashes (optional).
  */
 
 /**
@@ -245,7 +246,7 @@ function serializeOptions(schema, options) {
 /**
  * Serializes the command and its options into an arguments array.
  *
- * @param {string} command The literal name of the command.
+ * @param {string[]} command The literal name of the command.
  * @param {OptionsSchema} [schema] An options schema required by the command.
  * @param {object} [options] An options object according to the schema.
  * @returns {string[]} An arguments array that can be passed via command line.
@@ -330,6 +331,7 @@ async function execute(args, live, silent, configFile, config = {}) {
         stdio: ['ignore', output, output],
       });
       pid.on('exit', () => {
+        // @ts-expect-error - this is a TODO (v3) to fix and resolve a string here
         resolve();
       });
     } else {

js/releases/index.js

@@ -10,13 +10,13 @@ const DEFAULT_IGNORE = ['node_modules'];
 
 /**
  * Schema for the `upload-sourcemaps` command.
- * @type {OptionsSchema}
+ * @type {import('../helper').OptionsSchema}
  */
 const SOURCEMAPS_SCHEMA = require('./options/uploadSourcemaps');
 
 /**
  * Schema for the `deploys new` command.
- * @type {OptionsSchema}
+ * @type {import('../helper').OptionsSchema}
  */
 const DEPLOYS_SCHEMA = require('./options/deploys');
 
@@ -95,7 +95,7 @@ class Releases {
       commitFlags.push('--ignore-missing');
     }
 
-    return this.execute(['releases', 'set-commits', release].concat(commitFlags));
+    return this.execute(['releases', 'set-commits', release].concat(commitFlags), false);
   }
 
   /**

js/releases/options/deploys.js

@@ -1,3 +1,6 @@
+/**
+ * @type {import('../../helper').OptionsSchema}
+ */
 module.exports = {
   env: {
     param: '--env',

js/releases/options/uploadSourcemaps.js

@@ -1,3 +1,6 @@
+/**
+ * @type {import('../../helper').OptionsSchema}
+ */
 module.exports = {
   ignore: {
     param: '--ignore',

package.json

@@ -22,12 +22,14 @@
     "which": "^2.0.2"
   },
   "devDependencies": {
+    "@types/node": "^20.10.0",
     "@vercel/nft": "^0.22.1",
     "eslint": "^7.32.0",
     "eslint-config-prettier": "^8.5.0",
     "jest": "^27.5.1",
     "npm-run-all": "^4.1.5",
-    "prettier": "2.8.8"
+    "prettier": "2.8.8",
+    "typescript": "~5.8.3"
   },
   "optionalDependencies": {
     "@sentry/cli-darwin": "2.47.1",
@@ -49,6 +51,7 @@
     "test:watch": "jest --watch --notify",
     "test:eslint": "eslint bin/* scripts/**/*.js js/**/*.js",
     "test:prettier": "prettier --check  bin/* scripts/**/*.js js/**/*.js",
+    "check:types": "tsc --noEmit",
     "test:vercel-nft": "node scripts/test-vercel-nft.js"
   },
   "jest": {

tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "target": "ES2015",
+    "moduleResolution": "node",
+    "skipLibCheck": true
+  },
+  "include": ["js/**/*.js"],
+  "exclude": ["**/__tests__/**", "**/__mocks__/**"]
+}

yarn.lock

@@ -788,6 +788,13 @@
   resolved "https://registry.yarnpkg.com/@types/node/-/node-18.11.18.tgz#8dfb97f0da23c2293e554c5a50d61ef134d7697f"
   integrity sha512-DHQpWGjyQKSHj3ebjFI/wRKcqQcdR+MoFBygntYOZytCqNfkd2ZC4ARDJ2DQqhjH5p85Nnd3jhUJIXrszFX/JA==
 
+"@types/node@^20.10.0":
+  version "20.19.8"
+  resolved "https://registry.yarnpkg.com/@types/node/-/node-20.19.8.tgz#d4a81f631d9dc5015c6e608a102c83e19d03c9db"
+  integrity sha512-HzbgCY53T6bfu4tT7Aq3TvViJyHjLjPNaAS3HOuMc9pw97KHsUtXNX4L+wu59g1WnjsZSko35MbEqnO58rihhw==
+  dependencies:
+    undici-types "~6.21.0"
+
 "@types/prettier@^2.1.5":
   version "2.7.2"
   resolved "https://registry.yarnpkg.com/@types/prettier/-/prettier-2.7.2.tgz#6c2324641cc4ba050a8c710b2b251b377581fbf0"
@@ -3652,6 +3659,11 @@ typedarray-to-buffer@^3.1.5:
   dependencies:
     is-typedarray "^1.0.0"
 
+typescript@~5.8.3:
+  version "5.8.3"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.8.3.tgz#92f8a3e5e3cf497356f4178c34cd65a7f5e8440e"
+  integrity sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==
+
 unbox-primitive@^1.0.2:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/unbox-primitive/-/unbox-primitive-1.0.2.tgz#29032021057d5e6cdbd08c5129c226dff8ed6f9e"
@@ -3662,6 +3674,11 @@ unbox-primitive@^1.0.2:
     has-symbols "^1.0.3"
     which-boxed-primitive "^1.0.2"
 
+undici-types@~6.21.0:
+  version "6.21.0"
+  resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-6.21.0.tgz#691d00af3909be93a7faa13be61b3a5b50ef12cb"
+  integrity sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==
+
 universalify@^0.2.0:
   version "0.2.0"
   resolved "https://registry.yarnpkg.com/universalify/-/universalify-0.2.0.tgz#6451760566fa857534745ab1dde952d1b1761be0"