eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/src/rules/typeFormatting.js

@@ -19,10 +19,13 @@ export default iterateJsdoc(({
     genericDot = false,
     objectFieldIndent = '',
     objectFieldQuote = null,
-    objectFieldSeparator = null,
+    objectFieldSeparator = 'comma',
+    objectFieldSeparatorTrailingPunctuation = false,
     propertyQuotes = null,
     separatorForSingleObjectField = false,
     stringQuotes = 'single',
+    typeBracketSpacing = '',
+    unionSpacing = ' ',
   } = context.options[0] || {};
 
   const {
@@ -54,7 +57,10 @@ export default iterateJsdoc(({
         return tokens.name || tokens.description;
       });
 
-      const nameAndDesc = tag.source.slice(beginNameOrDescIdx);
+      const nameAndDesc = beginNameOrDescIdx === -1 ?
+        null :
+        tag.source.slice(beginNameOrDescIdx);
+
       const initialNumber = tag.source[0].number;
       const src = [
         // Get inevitably present tag from first `tag.source`
@@ -69,7 +75,7 @@ export default iterateJsdoc(({
               postName: '',
               postType: '',
             } : {}),
-            type: '{' + firstTypeLine + (!typeLines.length && lastTypeLine === undefined ? '}' : ''),
+            type: '{' + typeBracketSpacing + firstTypeLine + (!typeLines.length && lastTypeLine === undefined ? typeBracketSpacing + '}' : ''),
           },
         },
         // Get any intervening type lines
@@ -97,14 +103,14 @@ export default iterateJsdoc(({
       // Merge any final type line and name and description
       if (
         // Name and description may be already included if present with the tag
-        beginNameOrDescIdx > 0
+        nameAndDesc && beginNameOrDescIdx > 0
       ) {
         src.push({
           number: src.length + 1,
           source: '',
           tokens: {
             ...nameAndDesc[0].tokens,
-            type: lastTypeLine + '}',
+            type: lastTypeLine + typeBracketSpacing + '}',
           },
         });
 
@@ -125,7 +131,7 @@ export default iterateJsdoc(({
             }),
           );
         }
-      } else {
+      } else if (nameAndDesc) {
         if (lastTypeLine) {
           src.push({
             number: src.length + 1,
@@ -136,7 +142,7 @@ export default iterateJsdoc(({
               postTag: '',
               start: indent + ' ',
               tag: '',
-              type: lastTypeLine + '}',
+              type: lastTypeLine + typeBracketSpacing + '}',
             },
           });
         }
@@ -171,6 +177,14 @@ export default iterateJsdoc(({
         return tg;
       });
 
+      const initialEndSource = jsdoc.source.find(({
+        tokens: {
+          end,
+        },
+      }) => {
+        return end;
+      });
+
       jsdoc.source = [
         ...jsdoc.source.slice(0, firstTagIdx),
         ...jsdoc.tags.flatMap(({
@@ -179,24 +193,34 @@ export default iterateJsdoc(({
           return source;
         }),
       ];
+
+      if (initialEndSource && !jsdoc.source.at(-1)?.tokens?.end) {
+        jsdoc.source.push(initialEndSource);
+      }
     };
 
     /** @type {string[]} */
     const errorMessages = [];
-    let needToReport = false;
+
+    if (typeBracketSpacing && (!tag.type.startsWith(typeBracketSpacing) || !tag.type.endsWith(typeBracketSpacing))) {
+      errorMessages.push(`Must have initial and final "${typeBracketSpacing}" spacing`);
+    } else if (!typeBracketSpacing && ((/^\s/v).test(tag.type) || (/\s$/v).test(tag.type))) {
+      errorMessages.push('Must have no initial spacing');
+    }
+
+    // eslint-disable-next-line complexity -- Todo
     traverse(parsedType, (nde) => {
-      let typeFound = true;
       let errorMessage = '';
-      const initialType = stringify(
-        /** @type {import('jsdoc-type-pratt-parser').RootResult} */ (nde),
-      );
+
       switch (nde.type) {
         case 'JsdocTypeGeneric': {
           const typeNode = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (nde);
           if ('value' in typeNode.left && typeNode.left.value === 'Array') {
-            typeNode.meta.brackets = arrayBrackets;
-            errorMessage = `Array bracket style should be ${arrayBrackets}`;
-          } else {
+            if (typeNode.meta.brackets !== arrayBrackets) {
+              typeNode.meta.brackets = arrayBrackets;
+              errorMessage = `Array bracket style should be ${arrayBrackets}`;
+            }
+          } else if (typeNode.meta.dot !== genericDot) {
             typeNode.meta.dot = genericDot;
             errorMessage = `Dot usage should be ${genericDot}`;
           }
@@ -206,22 +230,31 @@ export default iterateJsdoc(({
 
         case 'JsdocTypeObject': {
           const typeNode = /** @type {import('jsdoc-type-pratt-parser').ObjectResult} */ (nde);
-          typeNode.meta.separator = objectFieldSeparator ?? undefined;
-          typeNode.meta.separatorForSingleObjectField = separatorForSingleObjectField;
-          typeNode.meta.propertyIndent = objectFieldIndent;
-          errorMessage = `Inconsistent ${objectFieldSeparator} usage`;
+          if (
+            /* c8 ignore next -- Guard */
+            (typeNode.meta.separator ?? 'comma') !== objectFieldSeparator ||
+            (typeNode.meta.separatorForSingleObjectField ?? false) !== separatorForSingleObjectField ||
+            (typeNode.meta.propertyIndent ?? '') !== objectFieldIndent ||
+            (typeNode.meta.trailingPunctuation ?? false) !== objectFieldSeparatorTrailingPunctuation
+          ) {
+            typeNode.meta.separator = objectFieldSeparator;
+            typeNode.meta.separatorForSingleObjectField = separatorForSingleObjectField;
+            typeNode.meta.propertyIndent = objectFieldIndent;
+            typeNode.meta.trailingPunctuation = objectFieldSeparatorTrailingPunctuation;
+            errorMessage = `Inconsistent ${objectFieldSeparator} separator usage`;
+          }
+
           break;
         }
 
         case 'JsdocTypeObjectField': {
           const typeNode = /** @type {import('jsdoc-type-pratt-parser').ObjectFieldResult} */ (nde);
-          if (objectFieldQuote ||
-            (typeof typeNode.key === 'string' && !(/\s/v).test(typeNode.key))
+          if ((objectFieldQuote ||
+            (typeof typeNode.key === 'string' && !(/\s/v).test(typeNode.key))) &&
+            typeNode.meta.quote !== (objectFieldQuote ?? undefined)
           ) {
             typeNode.meta.quote = objectFieldQuote ?? undefined;
             errorMessage = `Inconsistent object field quotes ${objectFieldQuote}`;
-          } else {
-            typeFound = false;
           }
 
           break;
@@ -230,13 +263,12 @@ export default iterateJsdoc(({
         case 'JsdocTypeProperty': {
           const typeNode = /** @type {import('jsdoc-type-pratt-parser').PropertyResult} */ (nde);
 
-          if (propertyQuotes ||
-            (typeof typeNode.value === 'string' && !(/\s/v).test(typeNode.value))
+          if ((propertyQuotes ||
+            (typeof typeNode.value === 'string' && !(/\s/v).test(typeNode.value))) &&
+            typeNode.meta.quote !== (propertyQuotes ?? undefined)
           ) {
             typeNode.meta.quote = propertyQuotes ?? undefined;
             errorMessage = `Inconsistent ${propertyQuotes} property quotes usage`;
-          } else {
-            typeFound = false;
           }
 
           break;
@@ -244,40 +276,64 @@ export default iterateJsdoc(({
 
         case 'JsdocTypeStringValue': {
           const typeNode = /** @type {import('jsdoc-type-pratt-parser').StringValueResult} */ (nde);
-          typeNode.meta.quote = stringQuotes;
-          errorMessage = `Inconsistent ${stringQuotes} string quotes usage`;
+          if (typeNode.meta.quote !== stringQuotes) {
+            typeNode.meta.quote = stringQuotes;
+            errorMessage = `Inconsistent ${stringQuotes} string quotes usage`;
+          }
+
+          break;
+        }
+
+        case 'JsdocTypeUnion': {
+          const typeNode = /** @type {import('jsdoc-type-pratt-parser').UnionResult} */ (nde);
+          /* c8 ignore next -- Guard */
+          if ((typeNode.meta?.spacing ?? ' ') !== unionSpacing) {
+            typeNode.meta = {
+              spacing: unionSpacing,
+            };
+            errorMessage = `Inconsistent "${unionSpacing}" union spacing usage`;
+          }
+
           break;
         }
 
         default:
-          typeFound = false;
           break;
       }
 
-      if (typeFound) {
-        const convertedType = stringify(/** @type {import('jsdoc-type-pratt-parser').RootResult} */ (nde));
-        if (initialType !== convertedType) {
-          needToReport = true;
-          errorMessages.push(errorMessage);
-        }
+      if (errorMessage) {
+        errorMessages.push(errorMessage);
       }
     });
 
-    if (needToReport) {
+    const differentResult = tag.type !==
+      typeBracketSpacing + stringify(parsedType) + typeBracketSpacing;
+
+    if (errorMessages.length && differentResult) {
       for (const errorMessage of errorMessages) {
         utils.reportJSDoc(
-          errorMessage, tag, enableFixer ? fix : null, true,
+          errorMessage, tag, enableFixer ? fix : null,
         );
       }
+    // Stringification may have been equal previously (and thus no error reported)
+    //   because the stringification doesn't preserve everything
+    } else if (differentResult) {
+      utils.reportJSDoc(
+        'There was an error with type formatting', tag, enableFixer ? fix : null,
+      );
     }
   };
 
   const tags = utils.getPresentTags([
     'param',
     'returns',
+    'type',
+    'typedef',
   ]);
   for (const tag of tags) {
-    checkTypeFormats(tag);
+    if (tag.type) {
+      checkTypeFormats(tag);
+    }
   }
 }, {
   iterateAllJsdocs: true,
@@ -320,9 +376,11 @@ export default iterateJsdoc(({
               'linebreak',
               'semicolon',
               'semicolon-and-linebreak',
-              null,
             ],
           },
+          objectFieldSeparatorTrailingPunctuation: {
+            type: 'boolean',
+          },
           propertyQuotes: {
             enum: [
               'double',
@@ -339,6 +397,12 @@ export default iterateJsdoc(({
               'single',
             ],
           },
+          typeBracketSpacing: {
+            type: 'string',
+          },
+          unionSpacing: {
+            type: 'string',
+          },
         },
         type: 'object',
       },

package/src/rules.d.ts

@@ -765,16 +765,13 @@ export interface Rules {
           genericDot?: boolean;
           objectFieldIndent?: string;
           objectFieldQuote?: "double" | "single" | null;
-          objectFieldSeparator?:
-            | "comma"
-            | "comma-and-linebreak"
-            | "linebreak"
-            | "semicolon"
-            | "semicolon-and-linebreak"
-            | null;
+          objectFieldSeparator?: "comma" | "comma-and-linebreak" | "linebreak" | "semicolon" | "semicolon-and-linebreak";
+          objectFieldSeparatorTrailingPunctuation?: boolean;
           propertyQuotes?: "double" | "single" | null;
           separatorForSingleObjectField?: boolean;
           stringQuotes?: "double" | "single";
+          typeBracketSpacing?: string;
+          unionSpacing?: string;
         }
       ];