ci: introduce jsdoc eslint plugin (warnings only) (#11681)

* ci: introduce jsdoc eslint plugin (warnings only) * fixed * fixed
2025-12-08 21:26:23 +00:00 · 2025-09-26 18:11:29 +02:00 · 2025-09-26 18:11:29 +02:00 · e0e7de14ca
commit e0e7de14ca
parent 83e3a8a3db
3 changed files with 165 additions and 0 deletions
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@ -1,4 +1,5 @@
 import eslint from "@eslint/js"
+import { jsdoc } from "eslint-plugin-jsdoc"
 import tseslint from "typescript-eslint"
 import globals from "globals"

@ -12,6 +13,7 @@ export default tseslint.config([
            "temp/**",
        ],
    },
+
    {
        files: ["**/*.ts"],
        languageOptions: {
@ -80,4 +82,9 @@ export default tseslint.config([
            "no-regex-spaces": "warn",
        },
    },
+
+    jsdoc({
+        config: 'flat/recommended-typescript', // change to 'flat/recommended-typescript-error' once warnings are fixed
+        files: ["src/**/*.ts"],
+    }),
 ])
--- a/package-lock.json
+++ b/package-lock.json
@ -51,6 +51,7 @@
        "chai-as-promised": "^7.1.2",
        "class-transformer": "^0.5.1",
        "eslint": "^9.36.0",
+        "eslint-plugin-jsdoc": "^60.3.0",
        "globals": "^16.4.0",
        "gulp": "^4.0.2",
        "gulp-rename": "^2.1.0",
@ -821,6 +822,37 @@
        "@jridgewell/sourcemap-codec": "^1.4.10"
      }
    },
+    "node_modules/@es-joy/jsdoccomment": {
+      "version": "0.60.0",
+      "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.60.0.tgz",
+      "integrity": "sha512-nZIXk63VbpIooJVXRWEhLIbVScE8rtbcPWr+zQ0ZQsnflvomq31DvB5hR0T1IoikvrNaF4pNoDOi5se5tmIZIg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.8",
+        "@typescript-eslint/types": "^8.44.1",
+        "comment-parser": "1.4.1",
+        "esquery": "^1.6.0",
+        "jsdoc-type-pratt-parser": "~5.4.0"
+      },
+      "engines": {
+        "node": ">=20.11.0"
+      }
+    },
+    "node_modules/@es-joy/jsdoccomment/node_modules/@typescript-eslint/types": {
+      "version": "8.44.1",
+      "resolved": "https://registry.npmjs.org/@typescript-eslint/types/-/types-8.44.1.tgz",
+      "integrity": "sha512-Lk7uj7y9uQUOEguiDIDLYLJOrYHQa7oBiURYVFqIpGxclAFQ78f6VUOM8lI2XEuNOKNB7XuvM2+2cMXAoq4ALQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/typescript-eslint"
+      }
+    },
    "node_modules/@eslint-community/eslint-utils": {
      "version": "4.9.0",
      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.9.0.tgz",
@ -3061,6 +3093,16 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/are-docs-informative": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz",
+      "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      }
+    },
    "node_modules/are-we-there-yet": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/are-we-there-yet/-/are-we-there-yet-3.0.1.tgz",
@ -4453,6 +4495,16 @@
        "node": ">=18"
      }
    },
+    "node_modules/comment-parser": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-1.4.1.tgz",
+      "integrity": "sha512-buhp5kePrmda3vhc5B9t7pUQXAb2Tnd0qgpkIhPhkHXxJpiPJ11H0ZEU0oBpJ2QztSbzG/ZxMj/CHsYJqRHmyg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 12.0.0"
+      }
+    },
    "node_modules/commondir": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/commondir/-/commondir-1.0.1.tgz",
@ -5483,6 +5535,44 @@
        }
      }
    },
+    "node_modules/eslint-plugin-jsdoc": {
+      "version": "60.3.1",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-60.3.1.tgz",
+      "integrity": "sha512-AEJRW4EgERmAGnMraZXu85r5xgtI9XqKlgKfaWkkFmHbMVMii2oz1dmz1b3GISJOkhfHNi4JsVC0RA+IPTrkBg==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@es-joy/jsdoccomment": "~0.60.0",
+        "are-docs-informative": "^0.0.2",
+        "comment-parser": "1.4.1",
+        "debug": "^4.4.3",
+        "escape-string-regexp": "^4.0.0",
+        "espree": "^10.4.0",
+        "esquery": "^1.6.0",
+        "html-entities": "^2.6.0",
+        "object-deep-merge": "^1.0.5",
+        "parse-imports-exports": "^0.2.4",
+        "semver": "^7.7.2",
+        "spdx-expression-parse": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=20.11.0"
+      },
+      "peerDependencies": {
+        "eslint": "^7.0.0 || ^8.0.0 || ^9.0.0"
+      }
+    },
+    "node_modules/eslint-plugin-jsdoc/node_modules/spdx-expression-parse": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/spdx-expression-parse/-/spdx-expression-parse-4.0.0.tgz",
+      "integrity": "sha512-Clya5JIij/7C6bRR22+tnGXbc4VKlibKSVj2iHvVeX5iMW7s1SIQlqu699JkODJJIhh/pUu8L0/VLh8xflD+LQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "spdx-exceptions": "^2.1.0",
+        "spdx-license-ids": "^3.0.0"
+      }
+    },
    "node_modules/eslint-scope": {
      "version": "8.4.0",
      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.4.0.tgz",
@ -7419,6 +7509,23 @@
      "dev": true,
      "license": "ISC"
    },
+    "node_modules/html-entities": {
+      "version": "2.6.0",
+      "resolved": "https://registry.npmjs.org/html-entities/-/html-entities-2.6.0.tgz",
+      "integrity": "sha512-kig+rMn/QOVRvr7c86gQ8lWXq+Hkv6CbAH1hLu+RG338StTpE8Z0b44SDVaqVu7HGKf27frdmUYEs9hTUX/cLQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/mdevils"
+        },
+        {
+          "type": "patreon",
+          "url": "https://patreon.com/mdevils"
+        }
+      ],
+      "license": "MIT"
+    },
    "node_modules/html-escaper": {
      "version": "2.0.2",
      "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
@ -8462,6 +8569,16 @@
        "js-yaml": "bin/js-yaml.js"
      }
    },
+    "node_modules/jsdoc-type-pratt-parser": {
+      "version": "5.4.0",
+      "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-5.4.0.tgz",
+      "integrity": "sha512-F9GQ+F1ZU6qvSrZV8fNFpjDNf614YzR2eF6S0+XbDjAcUI28FSoXnYZFjQmb1kFx3rrJb5PnxUH3/Yti6fcM+g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
    "node_modules/jsesc": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",
@ -10899,6 +11016,29 @@
        "node": ">=0.10.0"
      }
    },
+    "node_modules/object-deep-merge": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/object-deep-merge/-/object-deep-merge-1.0.5.tgz",
+      "integrity": "sha512-3DioFgOzetbxbeUq8pB2NunXo8V0n4EvqsWM/cJoI6IA9zghd7cl/2pBOuWRf4dlvA+fcg5ugFMZaN2/RuoaGg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "type-fest": "4.2.0"
+      }
+    },
+    "node_modules/object-deep-merge/node_modules/type-fest": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-4.2.0.tgz",
+      "integrity": "sha512-5zknd7Dss75pMSED270A1RQS3KloqRJA9XbXLe0eCxyw7xXFb3rd+9B0UQ/0E+LQT6lnrLviEolYORlRWamn4w==",
+      "dev": true,
+      "license": "(MIT OR CC0-1.0)",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/object-keys": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/object-keys/-/object-keys-1.1.1.tgz",
@ -11202,6 +11342,16 @@
        "node": ">=0.8"
      }
    },
+    "node_modules/parse-imports-exports": {
+      "version": "0.2.4",
+      "resolved": "https://registry.npmjs.org/parse-imports-exports/-/parse-imports-exports-0.2.4.tgz",
+      "integrity": "sha512-4s6vd6dx1AotCx/RCI2m7t7GCh5bDRUtGNvRfHSP2wbBQdMi67pPe7mtzmgwcaQ8VKK/6IB7Glfyu3qdZJPybQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "parse-statements": "1.0.11"
+      }
+    },
    "node_modules/parse-json": {
      "version": "2.2.0",
      "resolved": "https://registry.npmjs.org/parse-json/-/parse-json-2.2.0.tgz",
@ -11235,6 +11385,13 @@
        "node": ">=0.10.0"
      }
    },
+    "node_modules/parse-statements": {
+      "version": "1.0.11",
+      "resolved": "https://registry.npmjs.org/parse-statements/-/parse-statements-1.0.11.tgz",
+      "integrity": "sha512-HlsyYdMBnbPQ9Jr/VgJ1YF4scnldvJpJxCVx6KgqPL4dxppsWrJHCIIxQXMJrqGnsRkNPATbeMJ8Yxu7JMsYcA==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/pascalcase": {
      "version": "0.1.1",
      "resolved": "https://registry.npmjs.org/pascalcase/-/pascalcase-0.1.1.tgz",
--- a/package.json
+++ b/package.json
@ -132,6 +132,7 @@
    "chai-as-promised": "^7.1.2",
    "class-transformer": "^0.5.1",
    "eslint": "^9.36.0",
+    "eslint-plugin-jsdoc": "^60.3.0",
    "globals": "^16.4.0",
    "gulp": "^4.0.2",
    "gulp-rename": "^2.1.0",