fix(valid-types): parse distinctly for names vs. namepaths (#1552)

Also:
- chore: update jsdocccomment and jsdoc-type-pratt-parser
- chore: avoid `eval` in build script

Author: brettz9

docs/rules/valid-types.md

@@ -233,7 +233,18 @@ function quux() {
 /**
  * @typedef {string} UserStr%ng
  */
-// Message: Syntax error in namepath: UserStr%ng
+// Message: Syntax error in name: UserStr%ng
+
+/**
+ * @typedef {string} module:abc/def
+ */
+// Message: Syntax error in name: module:abc/def
+
+/**
+ * @typedef {string} module:abc/def
+ */
+// Settings: {"jsdoc":{"mode":"permissive"}}
+// Message: Syntax error in name: module:abc/def
 
 /**
  * @this

package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.67.2",
+    "@es-joy/jsdoccomment": "~0.68.1",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.4.3",
@@ -27,7 +27,7 @@
     "@babel/plugin-syntax-class-properties": "^7.12.13",
     "@babel/plugin-transform-flow-strip-types": "^7.27.1",
     "@babel/preset-env": "^7.28.3",
-    "@es-joy/escodegen": "^4.0.3",
+    "@es-joy/escodegen": "^4.2.0",
     "@es-joy/jsdoc-eslint-parser": "^0.24.0",
     "@eslint/core": "^0.16.0",
     "@hkdobrev/run-if-changed": "^0.6.3",
@@ -58,7 +58,7 @@
     "glob": "^11.0.3",
     "globals": "^16.4.0",
     "husky": "^9.1.7",
-    "jsdoc-type-pratt-parser": "^6.3.2",
+    "jsdoc-type-pratt-parser": "^6.3.3",
     "json-schema": "^0.4.0",
     "json-schema-to-typescript": "^15.0.4",
     "lint-staged": "^16.2.3",

pnpm-lock.yaml

@@ -36,11 +36,13 @@ for (const file of dirContents) {
      ' Property[key.name="meta"] Property[key.name="schema"]',
   );
   if (results[0]?.value) {
-    const schema = generate(results[0]?.value);
-
-    // eslint-disable-next-line no-eval -- Need some parser
-    const json = eval('JSON.stringify(' + schema + ', null, 2)');
-    const parsed = JSON.parse(json);
+    const schema = generate(results[0]?.value, {
+      format: {
+        json: true,
+        quotes: 'double',
+      },
+    });
+    const parsed = JSON.parse(schema);
 
     let initial = '';
     if (Array.isArray(parsed)) {

src/bin/generateOptions.js

@@ -96,6 +96,7 @@ import esquery from 'esquery';
  *   isNamepathReferencingTag: IsNamepathX,
  *   isNamepathOrUrlReferencingTag: IsNamepathX,
  *   tagMightHaveNameOrNamepath: IsNamepathX,
+ *   tagMightHaveName: IsNamepathX
  * }} BasicUtils
  */
 
@@ -530,6 +531,8 @@ import esquery from 'esquery';
  *   isNamepathReferencingTag: IsNamepathX,
  *   isNamepathOrUrlReferencingTag: IsNamepathX,
  *   tagMightHaveNameOrNamepath: IsNamepathX,
+ *   tagMightHaveName: IsNamepathX,
+ *   tagMightHaveNamepath: IsNamepathX,
  *   getTagStructureForMode: GetTagStructureForMode,
  *   mayBeUndefinedTypeTag: MayBeUndefinedTypeTag,
  *   hasValueOrExecutorHasNonEmptyResolveValue: HasValueOrExecutorHasNonEmptyResolveValue,
@@ -618,14 +621,16 @@ const getBasicUtils = (context, {
     'isNamepathReferencingTag',
     'isNamepathOrUrlReferencingTag',
     'tagMightHaveNameOrNamepath',
+    'tagMightHaveName',
+    'tagMightHaveNamepath',
   ]) {
     /** @type {IsNamepathX} */
     utils[
-      /** @type {"isNameOrNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNameOrNamepath"} */ (
+      /** @type {"isNameOrNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNameOrNamepath"|"tagMightHaveName"} */ (
         method
       )] = (tagName) => {
       return jsdocUtils[
-        /** @type {"isNameOrNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNameOrNamepath"} */
+        /** @type {"isNameOrNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNameOrNamepath"|"tagMightHaveName"} */
         (method)
       ](tagName);
     };

src/iterateJsdoc.js

@@ -1145,6 +1145,37 @@ const tagMightHaveNameOrNamepath = (tag, tagMap = tagStructure) => {
     namepathTypes.has(/** @type {string} */ (nampathRole));
 };
 
+/**
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {boolean}
+ */
+const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
+  const tagStruct = ensureMap(tagMap, tag);
+
+  const nampathRole = tagStruct.get('namepathRole');
+
+  return nampathRole !== false &&
+    [
+      'namepath-defining',
+      'namepath-referencing',
+    ].includes(/** @type {string} */ (nampathRole));
+};
+
+/**
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {boolean}
+ */
+const tagMightHaveName = (tag, tagMap = tagStructure) => {
+  const tagStruct = ensureMap(tagMap, tag);
+
+  const nampathRole = tagStruct.get('namepathRole');
+
+  return nampathRole !== false &&
+    nampathRole === 'name-defining';
+};
+
 /**
  * @param {string} tag
  * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
@@ -1907,7 +1938,9 @@ export {
   setTagStructure,
   strictNativeTypes,
   tagMightHaveEitherTypeOrNamePosition,
+  tagMightHaveName,
   tagMightHaveNameOrNamepath,
+  tagMightHaveNamepath,
   tagMightHaveNamePosition,
   tagMightHaveTypePosition,
   tagMissingRequiredTypeOrNamepath,

src/jsdocUtils.js

@@ -1,7 +1,7 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 import {
   parse,
-  // parseName,
+  parseName,
   parseNamePath,
   traverse,
   tryParse,
@@ -99,6 +99,23 @@ const tryParsePathIgnoreError = (path, mode) => {
   return false;
 };
 
+/**
+ * @param {string} name
+ * @param {import('jsdoc-type-pratt-parser').ParseMode|"permissive"} mode
+ * @returns {boolean}
+ */
+const tryParseNameIgnoreError = (name, mode) => {
+  try {
+    parseName(name, mode === 'permissive' ? 'jsdoc' : mode);
+
+    return true;
+  } catch {
+    // Keep the original error for including the whole type
+  }
+
+  return false;
+};
+
 // eslint-disable-next-line complexity
 export default iterateJsdoc(({
   context,
@@ -350,12 +367,12 @@ export default iterateJsdoc(({
     }
 
     // VALID NAME/NAMEPATH
-    const hasNameOrNamepathPosition = (
+    const hasNamepathPosition = (
       tagMustHaveNamePosition !== false ||
-      utils.tagMightHaveNameOrNamepath(tag.tag)
+      utils.tagMightHaveNamepath(tag.tag)
     ) && Boolean(tag.name);
 
-    if (hasNameOrNamepathPosition) {
+    if (hasNamepathPosition) {
       if (mode !== 'jsdoc' && tag.tag === 'template') {
         if (!tryParsePathIgnoreError(
           // May be an issue with the commas of
@@ -373,6 +390,12 @@ export default iterateJsdoc(({
       }
     }
 
+    const hasNamePosition = utils.tagMightHaveName(tag.tag) &&
+      Boolean(tag.name);
+    if (hasNamePosition && !tryParseNameIgnoreError(tag.name, mode)) {
+      report(`Syntax error in name: ${tag.name}`, null, tag);
+    }
+
     for (const inlineTag of tag.inlineTags) {
       if (inlineTags.has(inlineTag.tag) && !inlineTag.text && !inlineTag.namepathOrURL) {
         report(`Inline tag "${inlineTag.tag}" missing content`, null, tag);

src/rules/validTypes.js

@@ -233,10 +233,41 @@ export default /** @type {import('../index.js').TestCases} */ ({
       errors: [
         {
           line: 3,
-          message: 'Syntax error in namepath: UserStr%ng',
+          message: 'Syntax error in name: UserStr%ng',
         },
       ],
     },
+    {
+      code: `
+          /**
+           * @typedef {string} module:abc/def
+           */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Syntax error in name: module:abc/def',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           * @typedef {string} module:abc/def
+           */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'Syntax error in name: module:abc/def',
+        },
+      ],
+      settings: {
+        jsdoc: {
+          mode: 'permissive',
+        },
+      },
+    },
     {
       code: `
           /**