chore(eslint): enable JSDoc parameter and type checks (#9566)

Author: BridgeAR

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
@@ -544,7 +544,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
@@ -772,7 +772,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) {
@@ -878,7 +878,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
  */
@@ -961,7 +961,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) {
@@ -1041,7 +1041,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])
@@ -1374,7 +1374,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) {
@@ -1890,7 +1890,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) {
@@ -1910,7 +1910,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
  */
@@ -1954,8 +1954,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 = {
@@ -2067,7 +2067,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) {
@@ -2091,7 +2091,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

@@ -906,6 +906,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

@@ -164,6 +164,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) {
@@ -175,6 +176,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 = {}