Add 'jsdoc/valid-types' rule to our eslint config (#646)

## Summary: Apparently flowgen tries to convert types in comments from TS to Flow syntax. It will fail to convert a file with invalid TS types in their docstrings. This PR fixes existing issues and prevents future regressions. I'm not sure why the errors it caught weren't causing flowgen to fail, but there was such an issue in #636. Issue: None ## Test plan: - yarn lint Author: kevinbarabash Reviewers: jeresig Required Reviewers: Approved By: jeresig Checks: ✅ codecov/project, ✅ Test (macos-latest, 16.x), ✅ CodeQL, ✅ Lint, typecheck, and coverage check (ubuntu-latest, 16.x), ✅ Prime node_modules cache for primary configuration (ubuntu-latest, 16.x), ✅ gerald, ⏭ dependabot, ✅ Analyze (javascript) Pull Request URL: #646
Khan · Apr 14, 2023 · 4f5821e · 4f5821e
1 parent d3ad2a7
commit 4f5821e
Show file tree

Hide file tree

Showing 7 changed files with 61 additions and 7 deletions.
diff --git a/.changeset/mean-trains-compete.md b/.changeset/mean-trains-compete.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -1,7 +1,15 @@
 /* eslint-disable import/no-commonjs */
 module.exports = {
     extends: ["./packages/eslint-config-khan/index.js"],
-    plugins: ["@babel", "import", "jest", "promise", "monorepo", "disable"],
+    plugins: [
+        "@babel",
+        "import",
+        "jest",
+        "jsdoc",
+        "promise",
+        "monorepo",
+        "disable",
+    ],
     settings: {
         "eslint-plugin-disable": {
             paths: {
@@ -134,6 +142,11 @@ module.exports = {
          */
         "jest/no-focused-tests": "error",
 
+        /**
+         * jsdoc rules
+         */
+        "jsdoc/valid-types": "error",
+
         /**
          * promise rules
          */

diff --git a/package.json b/package.json
@@ -48,6 +48,7 @@
     "eslint-plugin-eslint-comments": "^3.2.0",
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-jest": "27.2.1",
+    "eslint-plugin-jsdoc": "^41.1.1",
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-plugin-monorepo": "^0.3.2",
     "eslint-plugin-prettier": "^4.2.1",

diff --git a/packages/wonder-stuff-core/src/values.ts b/packages/wonder-stuff-core/src/values.ts
@@ -1,7 +1,7 @@
 /**
  * Return an array of the enumerable property values of an object.
  *
- * @param {$ReadOnly<interface {[mixed]: V}>} obj The object for which the values are
+ * @param {Readonly<{[K: mixed]: V}>} obj The object for which the values are
  * to be returned.
  * @returns {Array<V>} An array of the enumerable property values of the object.
  */

diff --git a/packages/wonder-stuff-i18n/src/plugins/i18n-plugin.ts b/packages/wonder-stuff-i18n/src/plugins/i18n-plugin.ts
@@ -240,7 +240,7 @@ export default class I18nPlugin {
      * Go through all of the JS assets and insert translated strings for every
      * locale that we're currently translating into.
      *
-     * @param {assets: Object<string, Object>, translatedStrings: Object} options
+     * @param {{assets: Assets, translatedStrings: TranslatedStrings}} options
      * @returns {Object<string, string>} a map of old file hashes to new hashes
      */
     translateAssets({
@@ -376,7 +376,7 @@ export default class I18nPlugin {
      * Update manifest files so that they point to the correct location of
      * the translated files.
      *
-     * @param {assets: Object<string, Object>, hashMap: <string, string>} options
+     * @param {{assets: Assets, hashMap: HashMaps}} options
      */
     localizeManifests({assets, hashMap}: {assets: Assets; hashMap: HashMaps}) {
         const {locales, timing, shouldLocalizeManifest, getLocalePath} =

diff --git a/packages/wonder-stuff-server/src/trace.ts b/packages/wonder-stuff-server/src/trace.ts
@@ -18,7 +18,7 @@ interface ITrace {
      *
      * @param {string} action The name of the action being traced.
      * @param {string} message A message to be logged along side the action
-     * @param {TReq: RequestWithLog<$Request>} [request] The request being
+     * @param {{TReq: RequestWithLog<$Request>}} [request] The request being
      * fulfilled. This is used to determine if a request-scoped logger can be used.
      * @returns {ITraceSession} The new trace session that was created and is to be
      * used to end the session.

diff --git a/yarn.lock b/yarn.lock
@@ -1263,6 +1263,15 @@
     enabled "2.0.x"
     kuler "^2.0.0"
 
+"@es-joy/jsdoccomment@~0.37.0":
+  version "0.37.0"
+  resolved "https://registry.yarnpkg.com/@es-joy/jsdoccomment/-/jsdoccomment-0.37.0.tgz#aaafb4bb6c88288aa7899aef0f3b1b851c36f908"
+  integrity sha512-hjK0wnsPCYLlF+HHB4R/RbUjOWeLW2SlarB67+Do5WsKILOkmIZvvPJFbtWSmbypxcjpoECLAMzoao0D4Bg5ZQ==
+  dependencies:
+    comment-parser "1.3.1"
+    esquery "^1.4.0"
+    jsdoc-type-pratt-parser "~4.0.0"
+
 "@eslint-community/eslint-utils@^4.2.0":
   version "4.2.0"
   resolved "https://registry.yarnpkg.com/@eslint-community/eslint-utils/-/eslint-utils-4.2.0.tgz#a831e6e468b4b2b5ae42bf658bea015bf10bc518"
@@ -2698,6 +2707,11 @@ anymatch@^3.0.3, anymatch@~3.1.2:
   resolved "https://registry.yarnpkg.com/aproba/-/aproba-2.0.0.tgz#52520b8ae5b569215b354efc0caa3fe1e45a8adc"
   integrity sha512-lYe4Gx7QT+MKGbDsA+Z+he/Wtef0BiwDOlK/XkBrdfsh9J/jPPXbX0tE9x9cl27Tmu5gg3QUbUrQYa/y+KOHPQ==
 
+are-docs-informative@^0.0.2:
+  version "0.0.2"
+  resolved "https://registry.yarnpkg.com/are-docs-informative/-/are-docs-informative-0.0.2.tgz#387f0e93f5d45280373d387a59d34c96db321963"
+  integrity sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==
+
 are-we-there-yet@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/are-we-there-yet/-/are-we-there-yet-2.0.0.tgz#372e0e7bd279d8e94c653aaa1f67200884bf3e1c"
@@ -3436,6 +3450,11 @@ commander@^6.1.0, commander@^6.2.0:
   resolved "https://registry.yarnpkg.com/commander/-/commander-6.2.1.tgz#0792eb682dfbc325999bb2b84fddddba110ac73c"
   integrity sha512-U7VdrJFnJgo4xjrHpTzu0yrHPGImdsmD95ZlgYSEajAn2JKzDhDTPG9kBTefmObL2w/ngeZnilk+OV9CG3d7UA==
 
+[email protected]:
+  version "1.3.1"
+  resolved "https://registry.yarnpkg.com/comment-parser/-/comment-parser-1.3.1.tgz#3d7ea3adaf9345594aedee6563f422348f165c1b"
+  integrity sha512-B52sN2VNghyq5ofvUsqZjmk6YkihBX5vMSChmSK9v4ShjKf3Vk5Xcmgpw4o+iIgtrnM/u5FiMpz9VKb8lpBveA==
+
 compare-versions@^3.6.0:
   version "3.6.0"
   resolved "https://registry.yarnpkg.com/compare-versions/-/compare-versions-3.6.0.tgz#1a5689913685e5a87637b8d3ffca75514ec41d62"
@@ -4131,6 +4150,20 @@ [email protected]:
   dependencies:
     "@typescript-eslint/utils" "^5.10.0"
 
+eslint-plugin-jsdoc@^41.1.1:
+  version "41.1.1"
+  resolved "https://registry.yarnpkg.com/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-41.1.1.tgz#f5430aea369c4eb69c2fdc4030e09eb79d5f0518"
+  integrity sha512-dfH97DKLGtQ5dgEMzd+GSUuY+xX/yyAfjML3O0pEWmMMpylsG6Ro65s4ziYXKmixiENYK9CTQxCVRGqZUFN2Mw==
+  dependencies:
+    "@es-joy/jsdoccomment" "~0.37.0"
+    are-docs-informative "^0.0.2"
+    comment-parser "1.3.1"
+    debug "^4.3.4"
+    escape-string-regexp "^4.0.0"
+    esquery "^1.5.0"
+    semver "^7.3.8"
+    spdx-expression-parse "^3.0.1"
+
 eslint-plugin-jsx-a11y@^6.7.1:
   version "6.7.1"
   resolved "https://registry.yarnpkg.com/eslint-plugin-jsx-a11y/-/eslint-plugin-jsx-a11y-6.7.1.tgz#fca5e02d115f48c9a597a6894d5bcec2f7a76976"
@@ -4290,7 +4323,7 @@ esprima@^4.0.0, esprima@^4.0.1:
   resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71"
   integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==
 
-esquery@^1.4.2:
+esquery@^1.4.0, esquery@^1.4.2, esquery@^1.5.0:
   version "1.5.0"
   resolved "https://registry.yarnpkg.com/esquery/-/esquery-1.5.0.tgz#6ce17738de8577694edd7361c57182ac8cb0db0b"
   integrity sha512-YQLXUplAwJgCydQ78IMJywZCceoqk1oH01OERdSAJc/7U2AylwjhSCLDEtqwg811idIS/9fIU5GjG73IgjKMVg==
@@ -6136,6 +6169,11 @@ js2xmlparser@^4.0.2:
   dependencies:
     xmlcreate "^2.0.4"
 
+jsdoc-type-pratt-parser@~4.0.0:
+  version "4.0.0"
+  resolved "https://registry.yarnpkg.com/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz#136f0571a99c184d84ec84662c45c29ceff71114"
+  integrity sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==
+
 jsdoc@^4.0.0:
   version "4.0.2"
   resolved "https://registry.yarnpkg.com/jsdoc/-/jsdoc-4.0.2.tgz#a1273beba964cf433ddf7a70c23fd02c3c60296e"
@@ -8530,7 +8568,7 @@ spdx-exceptions@^2.1.0:
   resolved "https://registry.yarnpkg.com/spdx-exceptions/-/spdx-exceptions-2.3.0.tgz#3f28ce1a77a00372683eade4a433183527a2163d"
   integrity sha512-/tTrYOC7PPI1nUAgx34hUpqXuyJG+DTHJTnIULG4rDygi4xu/tfgmq1e1cIRwRzwZgo4NLySi+ricLkZkw4i5A==
 
-spdx-expression-parse@^3.0.0:
+spdx-expression-parse@^3.0.0, spdx-expression-parse@^3.0.1:
   version "3.0.1"
   resolved "https://registry.yarnpkg.com/spdx-expression-parse/-/spdx-expression-parse-3.0.1.tgz#cf70f50482eefdc98e3ce0a6833e4a53ceeba679"
   integrity sha512-cbqHunsQWnJNE6KhVSMsMeH5H/L9EpymbzqTQ3uLwNCLZ1Q481oWaofqH7nO6V07xlXwY6PhQdQ2IedWx/ZK4Q==