feat: Move javascript files to native typescript (#2989)

(closes #2617)
(closes [CLI-142](https://linear.app/getsentry/issue/CLI-142/use-typescript-to-generate-type-declarations))

This PR migrates all JavaScript files in the `lib/` directory to native TypeScript, removing the need for JSDoc type annotations and improving type safety.

### Main Changes

- Converted all `.js` files to `.ts` with proper TypeScript syntax
- Changed module system from CommonJS to ES6 modules for better TypeScript interoperability
- Updated exports to use ES6 `export` syntax instead of `module.exports`
- All types are now exported as named exports for better type inference and IDE support
- `OptionsSchema` is now a union to satisfy `SOURCEMAPS_OPTIONS`, as this one didn't had the required `param`
- The exports of `lib/releases/options` has changed its name

### Breaking Changes

**Module Exports**
- **Before**: `module.exports = SentryCli;` (CommonJS)
- **After**: `export class SentryCli { ... }` (ES6 named export)

We could have maintained backwards compatibility with `export = SentryCli;`. The only problem were the types which needed to be exported as well. With ES6 named exports, we can now export all types alongside the class.

### Internal Improvements

Simplified `Release` constructor
- **Before**: `new Releases({ ...this.options, configFile })` - configFile was merged into options
- **After**: `new Releases(this.options, configFile)` - two separate parameters

With 2 parameters it's easier to maintain and makes the separation of concerns clearer.

Author: JPeer264

CHANGELOG.md

@@ -29,6 +29,25 @@ The following changes only apply when using `sentry-cli` via the npm package [`@
 - Removed the `apiKey` option from `SentryCliOptions` ([#2935](https://github.com/getsentry/sentry-cli/pull/2935)). If you are using `apiKey`, you need to generate and use an [Auth Token](https://docs.sentry.io/account/auth-tokens/) via the `authToken` option, instead.
 - Removed the `useArtifactBundle` option from `SentryCliUploadSourceMapsOptions` ([#3002](https://github.com/getsentry/sentry-cli/pull/3002)). This deprecated option was a no-op that users should simply stop passing.
 - Drop support for Node.js <18. The minimum required Node.js version is now 18.0.0 ([#2985](https://github.com/getsentry/sentry-cli/issues/2985)).
+- The type export `SentryCliReleases` has been removed.
+- The JavaScript wrapper now uses named exports instead of default exports ([#2989](https://github.com/getsentry/sentry-cli/pull/2989)). You need to update your imports:
+  ```js
+  // Old (default import)
+  const SentryCli = require('@sentry/cli');
+
+  // New (named import)
+  const { SentryCli } = require('@sentry/cli');
+  ```
+
+  For ESM imports:
+  ```js
+  // Old
+  import SentryCli from '@sentry/cli';
+
+  // New
+  import { SentryCli } from '@sentry/cli';
+  ```
+
 
 ### Improvements
 

bin/sentry-cli

@@ -3,7 +3,7 @@
 'use strict';
 
 const childProcess = require('child_process');
-const SentryCli = require('../js');
+const { SentryCli } = require('../js');
 
 const child = childProcess
   .spawn(SentryCli.getPath(), process.argv.slice(2), {

jest.config.js

@@ -1,4 +1,7 @@
 module.exports = {
   setupFiles: ['<rootDir>/setupTests.js'],
   testPathIgnorePatterns: ['<rootDir>/src/'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
 };

lib/__tests__/helper.test.js

@@ -2,7 +2,7 @@ const os = require('os');
 
 const helper = require('../helper');
 
-const SOURCEMAPS_OPTIONS = require('../releases/options/uploadSourcemaps');
+const { SOURCEMAPS_OPTIONS } = require('../releases/options/uploadSourcemaps');
 
 describe('SentryCli helper', () => {
   test('call sentry-cli --version', () => {

lib/helper.js lib/helper.tslib/helper.js renamed to lib/helper.ts

@@ -1,9 +1,10 @@
 'use strict';
 
-const os = require('os');
-const path = require('path');
-const fs = require('fs');
-const childProcess = require('child_process');
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import * as childProcess from 'node:child_process';
+import { SentryCliOptions } from './types';
 
 const BINARY_DISTRIBUTIONS = [
   { packageName: '@sentry/cli-darwin', subpath: 'bin/sentry-cli' },
@@ -23,9 +24,9 @@ const BINARY_DISTRIBUTIONS = [
  * Without this, the binary can be detected as an asset and included by bundlers
  * that use @vercel/nft.
  *
- * @returns {string} The path to the sentry-cli binary
+ * @returns The path to the sentry-cli binary
  */
-function getFallbackBinaryPath() {
+function getFallbackBinaryPath(): string {
   const parts = [];
   parts.push(__dirname);
   parts.push('..');
@@ -93,9 +94,9 @@ function getDistributionForThisPlatform() {
 /**
  * Throws an error with a message stating that Sentry CLI doesn't support the current platform.
  *
- * @returns {never} nothing. It throws.
+ * @returns nothing. It throws.
  */
-function throwUnsupportedPlatformError() {
+function throwUnsupportedPlatformError(): void {
   throw new Error(
     `Unsupported operating system or architecture! Sentry CLI does not work on this architecture.
 
@@ -110,9 +111,9 @@ Sentry CLI supports:
  * Tries to find the installed Sentry CLI binary - either by looking into the relevant
  * optional dependencies or by trying to resolve the fallback binary.
  *
- * @returns {string} The path to the sentry-cli binary
+ * @returns The path to the sentry-cli binary
  */
-function getBinaryPath() {
+function getBinaryPath(): string {
   if (process.env.SENTRY_BINARY_PATH) {
     return process.env.SENTRY_BINARY_PATH;
   }
@@ -161,47 +162,41 @@ It seems like none of the "@sentry/cli" package's optional dependencies got inst
 
 /**
  * Will be used as the binary path when defined with `mockBinaryPath`.
- * @type {string | undefined}
  */
-let mockedBinaryPath;
+let mockedBinaryPath: string | undefined;
 
 /**
  * Overrides the default binary path with a mock value, useful for testing.
  *
- * @param {string} mockPath The new path to the mock sentry-cli binary
+ * @param mockPath The new path to the mock sentry-cli binary
  * @deprecated This was used in tests internally and will be removed in the next major version.
  */
 // TODO(v3): Remove this function
-function mockBinaryPath(mockPath) {
+function mockBinaryPath(mockPath: string) {
   mockedBinaryPath = mockPath;
 }
 
-/**
- * The javascript type of a command line option.
- * @typedef {'array'|'string'|'boolean'|'inverted-boolean'} OptionType
- */
-
-/**
- * Schema definition of a command line option.
- * @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).
- */
-
-/**
- * Schema definition for a command.
- * @typedef {Object.<string, OptionSchema>} OptionsSchema
- */
+export type OptionsSchema = Record<
+  string,
+  | {
+      param: string;
+      type: 'array' | 'string' | 'number' | 'boolean' | 'inverted-boolean';
+      invertedParam?: string;
+    }
+  | {
+      param?: never;
+      type: 'array' | 'string' | 'number' | 'boolean' | 'inverted-boolean';
+      invertedParam: string;
+    }
+>;
 
 /**
  * Serializes command line options into an arguments array.
  *
- * @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.
+ * @param schema An options schema required by the command.
+ * @param options An options object according to the schema.
  */
-function serializeOptions(schema, options) {
+function serializeOptions(schema: OptionsSchema, options: Record<string, unknown>): string[] {
   return Object.keys(schema).reduce((newOptions, option) => {
     const paramValue = options[option];
     if (paramValue === undefined || paramValue === null) {
@@ -246,20 +241,23 @@ function serializeOptions(schema, options) {
 /**
  * Serializes the command and its options into an arguments array.
  *
- * @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.
+ * @param command The literal name of the command.
+ * @param schema An options schema required by the command.
+ * @param options An options object according to the schema.
+ * @returns An arguments array that can be passed via command line.
  */
-function prepareCommand(command, schema, options) {
+function prepareCommand(
+  command: string[],
+  schema: OptionsSchema,
+  options: Record<string, unknown>
+): string[] {
   return command.concat(serializeOptions(schema || {}, options || {}));
 }
 
 /**
  * Returns the absolute path to the `sentry-cli` binary.
- * @returns {string}
  */
-function getPath() {
+function getPath(): string {
   return mockedBinaryPath !== undefined ? mockedBinaryPath : getBinaryPath();
 }
 
@@ -280,17 +278,23 @@ function getPath() {
  * const output = await execute(['--version']);
  * expect(output.trim()).toBe('sentry-cli x.y.z');
  *
- * @param {string[]} args Command line arguments passed to `sentry-cli`.
- * @param {boolean} live can be set to:
+ * @param args Command line arguments passed to `sentry-cli`.
+ * @param live can be set to:
  *  - `true` to inherit stdio and reject the promise if the command
  *    exits with a non-zero exit code.
  *  - `false` to not inherit stdio and return the output as a string.
- * @param {boolean} silent Disable stdout for silents build (CI/Webpack Stats, ...)
- * @param {string} [configFile] Relative or absolute path to the configuration file.
- * @param {import('./index').SentryCliOptions} [config] More configuration to pass to the CLI
- * @returns {Promise<string>} A promise that resolves to the standard output.
+ * @param silent Disable stdout for silents build (CI/Webpack Stats, ...)
+ * @param configFile Relative or absolute path to the configuration file.
+ * @param config More configuration to pass to the CLI
+ * @returns A promise that resolves to the standard output.
  */
-async function execute(args, live, silent, configFile, config = {}) {
+async function execute(
+  args: string[],
+  live: boolean,
+  silent: boolean,
+  configFile: string | undefined,
+  config: SentryCliOptions = {}
+): Promise<string> {
   const env = { ...process.env };
   if (configFile) {
     env.SENTRY_PROPERTIES = configFile;
@@ -353,7 +357,7 @@ function getProjectFlagsFromOptions({ projects = [] } = {}) {
   return projects.reduce((flags, project) => flags.concat('-p', project), []);
 }
 
-module.exports = {
+export {
   execute,
   getPath,
   getProjectFlagsFromOptions,

lib/index.js lib/index.tslib/index.js renamed to lib/index.ts

@@ -1,17 +1,17 @@
 'use strict';
 
-const pkgInfo = require('../package.json');
-const helper = require('./helper');
-const Releases = require('./releases');
+import * as pkgInfo from '../package.json';
+import * as helper from './helper';
+import { Releases } from './releases';
+import type { SentryCliOptions } from './types';
 
-/**
- * @typedef {import('./types').SentryCliOptions} SentryCliOptions
- * @typedef {import('./types').SentryCliUploadSourceMapsOptions} SentryCliUploadSourceMapsOptions
- * @typedef {import('./types').SourceMapsPathDescriptor} SourceMapsPathDescriptor
- * @typedef {import('./types').SentryCliNewDeployOptions} SentryCliNewDeployOptions
- * @typedef {import('./types').SentryCliCommitsOptions} SentryCliCommitsOptions
- * @typedef {import('./types').SentryCliReleases} SentryCliReleases
- */
+export type {
+  SentryCliOptions,
+  SentryCliUploadSourceMapsOptions,
+  SourceMapsPathDescriptor,
+  SentryCliNewDeployOptions,
+  SentryCliCommitsOptions,
+} from './types';
 
 /**
  * Interface to and wrapper around the `sentry-cli` executable.
@@ -28,55 +28,53 @@ const Releases = require('./releases');
  * const release = await cli.releases.proposeVersion());
  * console.log(release);
  */
-class SentryCli {
+export class SentryCli {
+  public releases: Releases;
+
   /**
    * Creates a new `SentryCli` instance.
    *
    * If the `configFile` parameter is specified, configuration located in the default
    * location and the value specified in the `SENTRY_PROPERTIES` environment variable is
    * overridden.
    *
-   * @param {string | null} [configFile] - Path to Sentry CLI config properties, as described in https://docs.sentry.io/learn/cli/configuration/#properties-files.
+   * @param configFile Path to Sentry CLI config properties, as described in https://docs.sentry.io/learn/cli/configuration/#properties-files.
    * By default, the config file is looked for upwards from the current path and defaults from ~/.sentryclirc are always loaded.
    * This value will update `SENTRY_PROPERTIES` env variable.
-   * @param {SentryCliOptions} [options] - More options to pass to the CLI
+   * @param options More options to pass to the CLI
    */
-  constructor(configFile, options) {
+  constructor(public configFile: string | null, public options: SentryCliOptions) {
     if (typeof configFile === 'string') {
       this.configFile = configFile;
     }
     this.options = options || { silent: false };
-    this.releases = new Releases({ ...this.options, configFile });
+    this.releases = new Releases(this.options, configFile);
   }
 
   /**
    * Returns the version of the installed `sentry-cli` binary.
-   * @returns {string}
    */
-  static getVersion() {
+  static getVersion(): string {
     return pkgInfo.version;
   }
 
   /**
    * Returns an absolute path to the `sentry-cli` binary.
-   * @returns {string}
    */
-  static getPath() {
+  static getPath(): string {
     return helper.getPath();
   }
 
   /**
    * See {helper.execute} docs.
-   * @param {string[]} args Command line arguments passed to `sentry-cli`.
-   * @param {boolean} live can be set to:
+   * @param args Command line arguments passed to `sentry-cli`.
+   * @param live can be set to:
    *  - `true` to inherit stdio and reject the promise if the command
    *    exits with a non-zero exit code.
    *  - `false` to not inherit stdio and return the output as a string.
-   * @returns {Promise<string>} A promise that resolves to the standard output.
+   * @returns A promise that resolves to the standard output.
    */
-  execute(args, live) {
+  execute(args: string[], live: boolean): Promise<string> {
     return helper.execute(args, live, this.options.silent, this.configFile, this.options);
   }
 }
-
-module.exports = SentryCli;

lib/logger.js lib/logger.tslib/logger.js renamed to lib/logger.ts

@@ -1,11 +1,9 @@
 'use strict';
 
-const format = require('util').format;
+import { format } from 'node:util';
 
-module.exports = class Logger {
-  constructor(stream) {
-    this.stream = stream;
-  }
+export class Logger {
+  constructor(public stream: NodeJS.WriteStream) {}
 
   log() {
     const message = format(...arguments);

lib/releases/__tests__/index.test.js

@@ -1,4 +1,4 @@
-const SentryCli = require('../..');
+const { SentryCli } = require('../..');
 
 describe('SentryCli releases', () => {
   afterEach(() => {
@@ -23,7 +23,7 @@ describe('SentryCli releases', () => {
     beforeEach(() => {
       mockExecute.mockClear();
       // eslint-disable-next-line global-require
-      const SentryCliLocal = require('../..');
+      const { SentryCli: SentryCliLocal } = require('../..');
       cli = new SentryCliLocal();
     });
     describe('new', () => {