chore(eslint): enable JSDoc parameter and type checks

ci/diagnose.js

@@ -224,7 +224,7 @@ const UNSUPPORTED_FRAMEWORKS = [
  *
  * @param {object} [options] diagnosis options
  * @param {string} [options.root] repository path to inspect
- * @param {NodeJS.ProcessEnv} [options.env] environment to inspect
+ * @param {typeof process.env} [options.env] environment to inspect
  * @param {Function} [options.execFile] command runner used for git checks
  * @param {string} [options.gitExecutable] trusted git executable used for git checks
  * @param {number} [options.maxFiles] maximum number of text files to scan
@@ -542,7 +542,7 @@ function checkUnsupportedFrameworks (results, unsupported, supported) {
  * @param {Array<object>} results mutable result list
  * @param {Array<object>} frameworks detected supported frameworks
  * @param {object} evidence repository evidence
- * @param {NodeJS.ProcessEnv} env environment
+ * @param {typeof process.env} env environment
  */
 function checkInitialization (results, frameworks, evidence, env) {
   if (!frameworks.length) return
@@ -770,7 +770,7 @@ function checkCypressConfiguration (results, evidence) {
  * @param {Array<object>} results mutable result list
  * @param {Array<object>} workflowFiles scanned CI workflow files
  * @param {object} evidence repository evidence
- * @param {NodeJS.ProcessEnv} env environment
+ * @param {typeof process.env} env environment
  */
 function checkCiConfiguration (results, workflowFiles, evidence, env) {
   if (!workflowFiles.length) {
@@ -876,7 +876,7 @@ function checkCiConfiguration (results, workflowFiles, evidence, env) {
  *
  * @param {Array<object>} results mutable result list
  * @param {string} root repository root
- * @param {NodeJS.ProcessEnv} env environment
+ * @param {typeof process.env} env environment
  * @param {Function} execFile command runner
  * @param {string|undefined} gitExecutable trusted git executable
  */
@@ -959,7 +959,7 @@ function checkGit (results, root, env, execFile, gitExecutable) {
  * Checks current environment variables relevant to Test Optimization.
  *
  * @param {Array<object>} results mutable result list
- * @param {NodeJS.ProcessEnv} env environment
+ * @param {typeof process.env} env environment
  * @param {object} evidence repository evidence
  */
 function checkCurrentEnvironment (results, env, evidence) {
@@ -1039,7 +1039,7 @@ function checkCurrentEnvironment (results, env, evidence) {
  * Checks current CI provider metadata.
  *
  * @param {Array<object>} results mutable result list
- * @param {NodeJS.ProcessEnv} env environment
+ * @param {typeof process.env} env environment
  */
 function checkCurrentCiMetadata (results, env) {
   const providerDetected = CURRENT_ENV_PROVIDER_KEYS.some(key => env[key])
@@ -1372,7 +1372,7 @@ function detectUnsupportedFrameworks (definitions, manifests, scripts) {
  * Collects useful boolean evidence from scanned files and environment.
  *
  * @param {Array<object>} textFiles scanned text files
- * @param {NodeJS.ProcessEnv} env environment
+ * @param {typeof process.env} env environment
  * @returns {object} evidence object
  */
 function collectEvidence (textFiles, env) {
@@ -1888,7 +1888,7 @@ function isTestSetupOrCiFile (file) {
  * @param {Function} execFile command runner
  * @param {string} root repository root
  * @param {string|undefined} gitExecutable trusted git executable
- * @param {NodeJS.ProcessEnv} env credential-free git environment
+ * @param {typeof process.env} env credential-free git environment
  * @returns {boolean} true if git runs
  */
 function canRunGit (execFile, root, gitExecutable, env) {
@@ -1908,7 +1908,7 @@ function canRunGit (execFile, root, gitExecutable, env) {
  * @param {Function} execFile command runner
  * @param {string} root repository root
  * @param {string} gitExecutable trusted git executable
- * @param {NodeJS.ProcessEnv} env credential-free git environment
+ * @param {typeof process.env} env credential-free git environment
  * @param {string[]} args git arguments
  * @returns {string} command output
  */
@@ -1952,8 +1952,8 @@ function findTrustedGitExecutable () {
  * Creates the minimal environment needed by read-only local git metadata commands.
  *
  * @param {string|undefined} gitExecutable trusted git executable
- * @param {NodeJS.ProcessEnv} sourceEnv source environment
- * @returns {NodeJS.ProcessEnv} credential-free git environment
+ * @param {typeof process.env} sourceEnv source environment
+ * @returns {typeof process.env} credential-free git environment
  */
 function getGitEnvironment (gitExecutable, sourceEnv) {
   const env = {
@@ -2065,7 +2065,7 @@ function hasRegisterInNodeOptions (nodeOptions) {
 /**
  * Checks whether environment contains branch or tag metadata.
  *
- * @param {NodeJS.ProcessEnv} env environment
+ * @param {typeof process.env} env environment
  * @returns {boolean} true if branch metadata exists
  */
 function hasBranchMetadata (env) {
@@ -2089,7 +2089,7 @@ function hasBranchMetadata (env) {
 /**
  * Checks whether environment contains commit SHA metadata.
  *
- * @param {NodeJS.ProcessEnv} env environment
+ * @param {typeof process.env} env environment
  * @returns {boolean} true if SHA metadata exists
  */
 function hasShaMetadata (env) {

ci/test-optimization-validation/cli.js

@@ -898,6 +898,7 @@ function getStaticFailure (framework, blocker, reportPath) {
  * @param {object} framework framework entry
  * @param {string} diagnosis blocker diagnosis
  * @param {string} reasonCode blocker id
+ * @param {string | undefined} blockerCategory blocker category
  * @returns {object} result
  */
 function getBasicNotReached (framework, diagnosis, reasonCode, blockerCategory) {

ci/test-optimization-validation/command-runner.js

@@ -522,7 +522,7 @@ function buildOfflineCaptureEnv ({ fixture, outputRoot }) {
  * @param {object} input offline validation inputs
  * @param {{manifestPath: string}} input.fixture authoritative cache fixture
  * @param {string} input.outputRoot pre-created payload output root
- * @returns {NodeJS.ProcessEnv} validation transport environment
+ * @returns {typeof process.env} validation transport environment
  */
 function buildOfflineValidationEnv ({ fixture, outputRoot }) {
   return {
@@ -551,7 +551,7 @@ function buildOfflineValidationEnv ({ fixture, outputRoot }) {
  * Rejects command-local assignments that can bypass validator-controlled offline routing.
  *
  * @param {object} command command to execute
- * @param {NodeJS.ProcessEnv} env validator environment overrides
+ * @param {typeof process.env} env validator environment overrides
  */
 function assertNoInlineValidationEnvOverrides (command, env) {
   if (!env[VALIDATION_MODE_ENV]) return

ci/test-optimization-validation/framework-adapters/cucumber.js

@@ -152,6 +152,7 @@ function getGeneratedStepsPath (testDirectory) {
  * Returns Cucumber arguments that select one existing feature.
  *
  * @param {string} filename selected Cucumber feature
+ * @param {string} cwd project working directory
  * @returns {string[]} focused Cucumber arguments
  */
 function getFocusedTestArgs (filename, cwd) {
@@ -163,6 +164,7 @@ function getFocusedTestArgs (filename, cwd) {
  *
  * @param {string} filename generated Cucumber feature
  * @param {string} stepsFile generated Cucumber step definitions
+ * @param {string} cwd project working directory
  * @returns {string[]} generated scenario arguments
  */
 function getGeneratedTestArgs (filename, stepsFile, cwd) {

eslint.config.mjs

@@ -293,11 +293,11 @@ export default [
       'jsdoc/no-blank-blocks': 'error',
       // TODO: Enable the rules that we want to use.
       'jsdoc/no-defaults': 'error',
-      'jsdoc/no-undefined-types': 'off',
+      'jsdoc/no-undefined-types': 'error',
       'jsdoc/reject-function-type': 'off',
       'jsdoc/require-jsdoc': 'off',
       'jsdoc/require-param-description': 'off', // Having a description is not crucial for now.
-      'jsdoc/require-param': 'off',
+      'jsdoc/require-param': 'error',
       'jsdoc/require-property-description': 'off',
       'jsdoc/require-returns-check': 'error',
       'jsdoc/require-returns-description': 'off',

integration-tests/ci-visibility-intake.js

@@ -462,7 +462,7 @@ class FakeCiVisIntake extends FakeAgent {
   // drain. `hardTimeout` is a backstop for a genuinely hung child — bump it per-call
   // only when a workload's child runtime is provably above the default.
   /**
-   * @param {import('child_process').ChildProcess | NodeJS.EventEmitter} childProcess
+   * @param {import('child_process').ChildProcess | import('node:events').EventEmitter} childProcess
    *   Source of the `'exit'` event. `exitCode` / `signalCode` are read synchronously
    *   so a child that has already exited is handled correctly.
    * @param {(message: object) => boolean} [payloadMatch] Per-message filter; falsy

integration-tests/coverage-child-process.spec.js

@@ -393,7 +393,7 @@ w.once('exit', code => process.exit(code))
       `  v8Dir: process.env.${V8_COVERAGE_ENV} || '',\n` +
       '}))\n')
 
-    /** @type {NodeJS.ProcessEnv} */
+    /** @type {typeof process.env} */
     const env = { ...process.env, [DISABLE_ENV]: '1' }
 
     await new Promise(/** @type {(resolve: (value?: void) => void, reject: (reason?: Error) => void) => void} */

integration-tests/coverage/runtime.js

@@ -41,7 +41,7 @@ function canonicalizePath (value) {
 }
 
 /**
- * @param {NodeJS.ProcessEnv} [env]
+ * @param {typeof process.env} [env]
  * @returns {boolean}
  */
 function isCoverageActive (env = process.env) {
@@ -65,7 +65,7 @@ function labelSuffix () {
 }
 
 /**
- * @param {NodeJS.ProcessEnv} [env]
+ * @param {typeof process.env} [env]
  * @returns {string}
  */
 function getCollectorRoot (env = process.env) {
@@ -242,11 +242,11 @@ function prependBootstrapRequire (nodeOptions) {
  * copies the parent's value to a child even when a custom env omits it, so omitting is not enough),
  * while a foreign directory the child set itself is preserved.
  *
- * @param {NodeJS.ProcessEnv | undefined} env
+ * @param {typeof process.env | undefined} env
  * @param {object} [options]
  * @param {string} [options.cwd]
  * @param {string | URL} [options.scriptPath]
- * @returns {NodeJS.ProcessEnv | undefined}
+ * @returns {typeof process.env | undefined}
  */
 function applyCoverageEnv (env, options = {}) {
   if (!isCoverageActive()) return env

integration-tests/cypress/cypress-reporting-instrumentation.spec.js

@@ -1586,7 +1586,7 @@ if (requestedVersion === 'latest' &&
      * @param {string} code filesystem error code
      * @param {string} filePath affected path
      * @param {string} [syscall] failed system call
-     * @returns {NodeJS.ErrnoException} filesystem error
+     * @returns {Error & { code: string, path: string, syscall: string }} filesystem error
      */
     function createFileError (code, filePath, syscall = 'open') {
       return Object.assign(new Error(`${code}: ${syscall} ${filePath}`), {

integration-tests/debugger/target-app/time-budget.js

@@ -63,6 +63,10 @@ const complexTypes = ['object', 'array', 'map', 'set']
 
 /**
  * Generate a complex nested object that requires a lot of async CDP calls to traverse
+ *
+ * @param {number} depth
+ * @param {number} breath
+ * @returns {Record<string, unknown>}
  */
 function generateObject (depth, breath) {
   const obj = {}

integration-tests/helpers/bun.js

@@ -7,8 +7,8 @@ const BUN_INSTALL = join(PROJECT_ROOT, 'node_modules', '.cache', 'bun')
 const BUN = join(PROJECT_ROOT, 'node_modules', '.bin', 'bun')
 
 /**
- * @param {NodeJS.ProcessEnv} [env]
- * @returns {NodeJS.ProcessEnv & { BUN_INSTALL: string }}
+ * @param {typeof process.env} [env]
+ * @returns {typeof process.env & { BUN_INSTALL: string }}
  */
 function withBun (env = process.env) {
   return { ...env, BUN_INSTALL }

integration-tests/helpers/fake-agent.js

@@ -519,7 +519,7 @@ function buildExpressServer (agent) {
     } else {
       agent.emit('debugger-diagnostics', {
         headers: req.headers,
-        payload: JSON.parse((/** @type {Express.Multer.File[]} */ (req.files))[0].buffer.toString()),
+        payload: JSON.parse((/** @type {Array<{ buffer: Buffer }>} */ (req.files))[0].buffer.toString()),
       })
     }
   })

integration-tests/helpers/index.js

@@ -182,8 +182,8 @@ function assertTelemetryPoints (pid, msgs, expectedTelemetryPoints) {
 /**
  * @typedef {childProcess.ChildProcess & {
  *   url: string,
- *   stdout: NodeJS.ReadableStream,
- *   stderr: NodeJS.ReadableStream
+ *   stdout: import('node:stream').Readable,
+ *   stderr: import('node:stream').Readable
  * }} SpawnedProcess
  */
 
@@ -277,7 +277,8 @@ function spawnProcAndExpectExit (filename, options = {}, stdioHandler, stderrHan
  *
  * @param {childProcess.ChildProcess|undefined} proc - Process to stop.
  * @param {object} [options] - Stop options.
- * @param {NodeJS.Signals} [options.signal] - Signal to send before escalating. Defaults to `SIGTERM`.
+ * @param {keyof import('node:os').SignalConstants} [options.signal] - Signal to send before escalating.
+ *   Defaults to `SIGTERM`.
  * @param {number} [options.timeoutMs] - Max wait per signal in milliseconds. Defaults to the stop-proc timeout.
  * @returns {Promise<void>}
  */
@@ -456,7 +457,7 @@ async function execHelperAsync (command, options) {
 
 /**
  * @param {string} tarballPath
- * @param {NodeJS.ProcessEnv} env
+ * @param {typeof process.env} env
  * @returns {Promise<void>}
  */
 async function packTarball (tarballPath, env) {
@@ -485,7 +486,7 @@ async function copyIntegrationTests (integrationTestsPaths, folder) {
  * Only one worker will pack the tarball, others will wait for it to be ready.
  *
  * @param {string} tarballPath - The path where the tarball should be created
- * @param {NodeJS.ProcessEnv} env - The environment to use for the pack command
+ * @param {typeof process.env} env - The environment to use for the pack command
  * @returns {Promise<void>}
  */
 async function packTarballWithLock (tarballPath, env) {
@@ -881,7 +882,7 @@ async function curlAndAssertMessage (agent, procOrUrl, fn, timeout, expectedMess
 
 /**
  * @param {number} port
- * @returns {NodeJS.ProcessEnv}
+ * @returns {typeof process.env}
  */
 function getCiVisAgentlessConfig (port) {
   // We remove GITHUB_WORKSPACE so the repository root is not assigned to dd-trace-js
@@ -899,7 +900,7 @@ function getCiVisAgentlessConfig (port) {
 
 /**
  * @param {number} port
- * @returns {NodeJS.ProcessEnv}
+ * @returns {typeof process.env}
  */
 function getCiVisEvpProxyConfig (port) {
   // We remove GITHUB_WORKSPACE so the repository root is not assigned to dd-trace-js

integration-tests/jest/jest.test-management.spec.js

@@ -2823,7 +2823,7 @@ describe(`jest@${JEST_VERSION} commonJS`, () => {
         })
 
     /**
-     * @param {Mocha.Done} done
+     * @param {(error?: Error) => void} done
      * @param {object} options
      * @param {boolean} options.isModified
      * @param {boolean} [options.isEfd]

integration-tests/mocha-parallel-files.spec.js

@@ -13,11 +13,11 @@ const fixturesDir = path.join(__dirname, 'mocha-parallel-files-fixtures')
  *   stdout: string,
  *   stderr: string,
  *   code: number|null,
- *   signal: NodeJS.Signals|null
+ *   signal: keyof import('node:os').SignalConstants|null
  * }} ChildResult
  *
  * @typedef {{
- *   killSignal?: NodeJS.Signals,
+ *   killSignal?: keyof import('node:os').SignalConstants,
  *   killOnFirstStdout?: boolean,
  *   timeoutMs?: number
  * }} RunOpts

integration-tests/mocha/mocha.spec.js

@@ -368,7 +368,7 @@ describe(`mocha@${MOCHA_VERSION}`, function () {
   const nonLegacyReportingOptions = ['evp proxy', 'agentless']
 
   nonLegacyReportingOptions.forEach((reportingOption) => {
-    let envVars = /** @type {NodeJS.ProcessEnv} */ ({})
+    let envVars = /** @type {typeof process.env} */ ({})
     context(`(${reportingOption}) can run and report`, () => {
       beforeEach(() => {
         if (reportingOption === 'agentless') {

integration-tests/vitest/vitest.core.spec.js

@@ -470,7 +470,7 @@ versions.forEach((version) => {
     /**
      * Runs Vitest typechecking with TIA settings and gathers all TIA payloads.
      *
-     * @param {{ suitesToSkip: string[], testFilter?: string, env?: NodeJS.ProcessEnv }} options
+     * @param {{ suitesToSkip: string[], testFilter?: string, env?: typeof process.env }} options
      * @param {(payloads: object[]) => void} assertPayloads
      * @returns {Promise<void>}
      */

packages/datadog-esbuild/src/utils.js

@@ -85,10 +85,25 @@ function getSource (url, { format }) {
   }
 }
 
+/**
+ * @typedef {[typeof LOAD_OPERATION, URL, object] | [typeof RESOLVE_OPERATION, string, object]} GetExportsOperation
+ */
+
+/**
+ * @typedef {{ done: false, value: GetExportsOperation } | { done: true, value: Set<string> }} GetExportsResult
+ */
+
+/**
+ * @typedef {{
+ *   next: (value?: unknown) => GetExportsResult,
+ *   throw: (error?: unknown) => GetExportsResult,
+ * }} GetExportsGenerator
+ */
+
 /**
  * Drives the generator returned by import-in-the-middle >=3.1.0 export discovery.
  *
- * @param {Generator<Array, Set<string>>} exportsGenerator Generator returned by getExports
+ * @param {GetExportsGenerator} exportsGenerator Generator returned by getExports
  * @param {(url: URL, context: object) => { source: string, format: string }} getSource
  * Function that loads module source
  * @returns {Set<string>}