chore: introduce jsdoc linter (#6899)

The linter ensures that our added JSDoc is using valid types that
can be picked up by the IDE. A couple of rules are either manually
fixed or are deactivated that would be too strict for now. Activate
more rules over time.

The linter is actually producing warnings instead of errors. This
is helpful to differentiate the JSDoc issues from other linter
errors. It will still fail the CI due to not accepting warnings.

Author: BridgeAR

LICENSE-3rdparty.csv

@@ -56,6 +56,7 @@ dev,chai,MIT,Copyright 2017 Chai.js Assertion Library
 dev,eslint,MIT,Copyright JS Foundation and other contributors https://js.foundation
 dev,eslint-plugin-cypress,MIT,Copyright (c) 2019 Cypress.io
 dev,eslint-plugin-import,MIT,Copyright 2015 Ben Mosher
+dev,eslint-plugin-jsdoc,BSD-3-Clause,Copyright Gajus Kuizinas
 dev,eslint-plugin-mocha,MIT,Copyright 2014 Mathias Schreck
 dev,eslint-plugin-n,MIT,Copyright 2015 Toru Nagashima
 dev,eslint-plugin-promise,ISC,jden and other contributors

eslint.config.mjs

@@ -2,6 +2,7 @@ import eslintPluginJs from '@eslint/js'
 import eslintPluginStylistic from '@stylistic/eslint-plugin'
 import eslintPluginCypress from 'eslint-plugin-cypress'
 import eslintPluginImport from 'eslint-plugin-import'
+import eslintPluginJSDoc from 'eslint-plugin-jsdoc'
 import eslintPluginMocha from 'eslint-plugin-mocha'
 import eslintPluginN from 'eslint-plugin-n'
 import eslintPluginPromise from 'eslint-plugin-promise'
@@ -35,6 +36,7 @@ export default [
   {
     name: 'dd-trace/global-ignore',
     ignores: [
+      '**/.bun', // Ignore autogenerated bun files
       '**/coverage', // Just coverage reports.
       '**/dist', // Generated
       '**/docs', // Any JS here is for presentation only.
@@ -55,7 +57,8 @@ export default [
       'packages/datadog-plugin-graphql/src/tools/transforms.js' // Inlined from apollo-graphql
     ]
   },
-  { name: '@eslint/js/recommended', ...eslintPluginJs.configs.recommended },
+  eslintPluginJs.configs.recommended,
+  eslintPluginJSDoc.configs['flat/recommended'],
   {
     // The following config and rules have been inlined from `eslint-config-standard` with the following modifications:
     // - Rules that were overridden elsewhere in this file have been removed.
@@ -85,6 +88,7 @@ export default [
     },
     plugins: {
       '@stylistic': eslintPluginStylistic,
+      jsdoc: eslintPluginJSDoc,
       import: eslintPluginImport,
       n: eslintPluginN,
       promise: eslintPluginPromise
@@ -215,6 +219,22 @@ export default [
       'import/no-duplicates': 'error',
       'import/no-named-default': 'error',
       'import/no-webpack-loader-syntax': 'error',
+      'jsdoc/check-tag-names': ['error', { definedTags: ['datadog'] }],
+      // TODO: Enable the rules that we want to use.
+      'jsdoc/check-types': 'off', // Should be activated, but it needs a couple of fixes.
+      // no-defaults: This should be activated, since the defaults will not be picked up in a description.
+      'jsdoc/no-defaults': 'off',
+      'jsdoc/no-undefined-types': 'off',
+      'jsdoc/reject-any-type': 'off', // Should be activated, but it needs a couple of fixes.
+      '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-property-description': 'off',
+      'jsdoc/require-returns-description': 'off',
+      'jsdoc/require-returns-type': 'off',
+      'jsdoc/require-returns': 'off',
+      'jsdoc/tag-lines': 'off', // Alignment is not important for us.
       'n/handle-callback-err': ['error', '^(err|error)$'],
       'n/no-callback-literal': 'error',
       'n/no-deprecated-api': 'error',

initialize.mjs

@@ -1,14 +1,14 @@
 /**
-  * This file serves one of two purposes, depending on how it's used.
-  *
-  * If used with --import, it will import init.js and register the loader hook.
-  * If used with --loader, it will act as the loader hook, except that it will
-  * also import init.js inside the source code of the entrypoint file.
-  *
-  * The result is that no matter how this file is used, so long as it's with
-  * one of the two flags, the tracer will always be initialized, and the loader
-  * hook will always be active for ESM support.
-  */
+ * This file serves one of two purposes, depending on how it's used.
+ *
+ * If used with --import, it will import init.js and register the loader hook.
+ * If used with --loader, it will act as the loader hook, except that it will
+ * also import init.js inside the source code of the entrypoint file.
+ *
+ * The result is that no matter how this file is used, so long as it's with
+ * one of the two flags, the tracer will always be initialized, and the loader
+ * hook will always be active for ESM support.
+ */
 
 /* eslint n/no-unsupported-features/node-builtins: ['error', { ignores: ['module.register'] }] */
 

integration-tests/ci-visibility/unskippable-test/test-unskippable.js

@@ -1,4 +1,5 @@
 /** Some comment */
+/* eslint-disable jsdoc/valid-types */
 /**
  * @datadog {"unskippable": true}
  */

integration-tests/cypress/e2e/spec.cy.js

@@ -1,7 +1,7 @@
+/* eslint-disable */
 /**
  * @datadog {"unskippable": true}
  */
-/* eslint-disable */
 describe('context', () => {
   it('passes', () => {
     cy.visit('/')

integration-tests/helpers/fake-agent.js

@@ -171,7 +171,8 @@ module.exports = class FakeAgent extends EventEmitter {
    * @param {number} [timeout=30_000] - The timeout in milliseconds.
    * @param {number} [expectedMessageCount=1] - The number of messages to expect.
    * @returns {Promise<void>} A promise that resolves when the telemetry message of type `requestType` is received.
-   *
+   */
+  /**
    * @overload
    * @param {Function} fn - The function to call with the telemetry message of type `requestType`.
    * @param {string} requestType - The request type to assert.

integration-tests/helpers/index.js

@@ -25,7 +25,7 @@ let shouldKill
 /**
  * @param {string} filename
  * @param {string} cwd
- * @param {string|function} expectedOut
+ * @param {string|((out: Promise<string>) => void)} expectedOut
  * @param {string} expectedSource
  */
 async function runAndCheckOutput (filename, cwd, expectedOut, expectedSource) {
@@ -69,7 +69,7 @@ let sandbox
  * This _must_ be used with the useSandbox function
  *
  * @param {string} filename
- * @param {string|function} expectedOut
+ * @param {string|((out: Promise<string>) => void)} expectedOut
  * @param {string[]} expectedTelemetryPoints
  * @param {string} expectedSource
  */
@@ -494,7 +494,7 @@ async function curl (url) {
 /**
  * @param {FakeAgent} agent
  * @param {string|{ then: (callback: () => Promise<string>) => Promise<string> }|URL} procOrUrl
- * @param {function} fn
+ * @param {(res: { headers: Record<string, string>, payload: unknown[] }) => void} fn
  * @param {number} [timeout]
  * @param {number} [expectedMessageCount]
  * @param {boolean} [resolveAtFirstSuccess]
@@ -557,7 +557,7 @@ function checkSpansForServiceName (spans, name) {
  * @param {string} cwd
  * @param {string} serverFile
  * @param {string|number} agentPort
- * @param {function} [stdioHandler]
+ * @param {(data: Buffer) => void} [stdioHandler]
  * @param {Record<string, string|undefined>} [additionalEnvArgs]
  */
 async function spawnPluginIntegrationTestProc (cwd, serverFile, agentPort, stdioHandler, additionalEnvArgs) {
@@ -594,8 +594,7 @@ function useEnv (env) {
 }
 
 /**
- * @param {unknown[]} args
- * @returns {object}
+ * @param {Parameters<createSandbox>} args
  */
 function useSandbox (...args) {
   before(async function () {

package.json

@@ -182,6 +182,7 @@
     "eslint": "^9.39.0",
     "eslint-plugin-cypress": "^5.2.0",
     "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-jsdoc": "^61.1.12",
     "eslint-plugin-mocha": "^11.2.0",
     "eslint-plugin-n": "^17.23.1",
     "eslint-plugin-promise": "^7.2.1",

packages/datadog-core/src/storage.js

@@ -15,7 +15,7 @@ const { AsyncLocalStorage } = require('async_hooks')
 class DatadogStorage extends AsyncLocalStorage {
   /**
    *
-   * @param store {Store}
+   * @param {Store} [store]
    * @override
    */
   enterWith (store) {
@@ -47,7 +47,7 @@ class DatadogStorage extends AsyncLocalStorage {
    * retrieved through `getHandle()` can also be passed in to be used as the
    * key. This is useful if you've stashed a handle somewhere and want to
    * retrieve the store with it.
-   * @param {{}} [handle]
+   * @param {object} [handle]
    * @returns {Store | undefined}
    * @override
    */
@@ -87,7 +87,7 @@ class DatadogStorage extends AsyncLocalStorage {
 
 /**
  * This is the map from handles to real stores, used in the class above.
- * @type {WeakMap<WeakKey, Store>}
+ * @type {WeakMap<WeakKey, Store|undefined>}
  */
 const stores = new WeakMap()
 
@@ -101,7 +101,7 @@ const storages = Object.create(null)
 
 /**
  *
- * @param namespace {string} the namespace to use
+ * @param {string} namespace The namespace to use
  * @returns {DatadogStorage}
  */
 function storage (namespace) {

packages/datadog-esbuild/src/utils.js

@@ -65,7 +65,11 @@ function getSource (url, { format }) {
 /**
  * Generates the pieces of code for the proxy module before the path
  *
- * @param {Object} moduleData { path, internal, context, excludeDefault }
+ * @param {object} moduleData
+ * @param {string} moduleData.path
+ * @param {boolean} moduleData.internal
+ * @param {object} moduleData.context
+ * @param {boolean} moduleData.excludeDefault
  * @returns {Promise<Map>}
  */
 async function processModule ({ path, internal, context, excludeDefault }) {