feat: add getNonJsdocComment for getting non-JSDoc comments above node

CHANGES.md

@@ -1,5 +1,9 @@
 # CHANGES for `@es-joy/jsdoccomment`
 
+## 0.44.0
+
+- feat: add `getNonJsdocComment` for getting non-JSDoc comments above node
+
 ## 0.43.1
 
 - fix: for `@template` name parsing, ensure (default-)bracketed name is not broken with internal spaces.

dist/index.cjs.cjs

@@ -887,12 +887,16 @@ const getReducedASTNode = function (node, sourceCode) {
  *   the comment for.
  * @param {import('eslint').SourceCode} sourceCode
  * @param {{maxLines: int, minLines: int, [name: string]: any}} settings
+ * @param {{nonJSDoc?: boolean}} [opts]
  * @returns {Token|null} The Block comment token containing the JSDoc comment
  *    for the given node or null if not found.
  * @private
  */
-const findJSDocComment = (astNode, sourceCode, settings) => {
+const findJSDocComment = (astNode, sourceCode, settings, opts = {}) => {
   var _parenthesisToken, _parenthesisToken2;
+  const {
+    nonJSDoc
+  } = opts;
   const {
     minLines,
     maxLines
@@ -921,7 +925,7 @@ const findJSDocComment = (astNode, sourceCode, settings) => {
     if (!tokenBefore || !isCommentToken(tokenBefore)) {
       return null;
     }
-    if (tokenBefore.type === 'Line') {
+    if (!nonJSDoc && tokenBefore.type === 'Line') {
       currentNode = tokenBefore;
       continue;
     }
@@ -932,7 +936,7 @@ const findJSDocComment = (astNode, sourceCode, settings) => {
   if (!tokenBefore || !currentNode.loc || !tokenBefore.loc) {
     return null;
   }
-  if (tokenBefore.type === 'Block' && /^\*\s/u.test(tokenBefore.value) && currentNode.loc.start.line - ( /** @type {import('eslint').AST.Token} */(_parenthesisToken = parenthesisToken) !== null && _parenthesisToken !== void 0 ? _parenthesisToken : tokenBefore).loc.end.line >= minLines && currentNode.loc.start.line - ( /** @type {import('eslint').AST.Token} */(_parenthesisToken2 = parenthesisToken) !== null && _parenthesisToken2 !== void 0 ? _parenthesisToken2 : tokenBefore).loc.end.line <= maxLines) {
+  if ((nonJSDoc && (tokenBefore.type !== 'Block' || !/^\*\s/u.test(tokenBefore.value)) || !nonJSDoc && tokenBefore.type === 'Block' && /^\*\s/u.test(tokenBefore.value)) && currentNode.loc.start.line - ( /** @type {import('eslint').AST.Token} */(_parenthesisToken = parenthesisToken) !== null && _parenthesisToken !== void 0 ? _parenthesisToken : tokenBefore).loc.end.line >= minLines && currentNode.loc.start.line - ( /** @type {import('eslint').AST.Token} */(_parenthesisToken2 = parenthesisToken) !== null && _parenthesisToken2 !== void 0 ? _parenthesisToken2 : tokenBefore).loc.end.line <= maxLines) {
     return tokenBefore;
   }
   return null;
@@ -956,6 +960,26 @@ const getJSDocComment = function (sourceCode, node, settings) {
   return findJSDocComment(reducedNode, sourceCode, settings);
 };
 
+/**
+ * Retrieves the comment preceding a given node.
+ *
+ * @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode
+ * @param {import('eslint').Rule.Node} node The AST node to get
+ *   the comment for.
+ * @param {{maxLines: int, minLines: int, [name: string]: any}} settings The
+ *   settings in context
+ * @returns {Token|null} The Block comment
+ *   token containing the JSDoc comment for the given node or
+ *   null if not found.
+ * @public
+ */
+const getNonJsdocComment = function (sourceCode, node, settings) {
+  const reducedNode = getReducedASTNode(node, sourceCode);
+  return findJSDocComment(reducedNode, sourceCode, settings, {
+    nonJSDoc: true
+  });
+};
+
 /**
  * @param {RegExpMatchArray & {
  *   indices: {
@@ -1228,6 +1252,7 @@ exports.estreeToString = estreeToString;
 exports.findJSDocComment = findJSDocComment;
 exports.getDecorator = getDecorator;
 exports.getJSDocComment = getJSDocComment;
+exports.getNonJsdocComment = getNonJsdocComment;
 exports.getReducedASTNode = getReducedASTNode;
 exports.getTokenizers = getTokenizers;
 exports.hasSeeWithLink = hasSeeWithLink;

dist/index.d.ts

@@ -169,6 +169,28 @@ declare function getJSDocComment(
     minLines: int;
   },
 ): Token | null;
+/**
+ * Retrieves the comment preceding a given node.
+ *
+ * @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode
+ * @param {import('eslint').Rule.Node} node The AST node to get
+ *   the comment for.
+ * @param {{maxLines: int, minLines: int, [name: string]: any}} settings The
+ *   settings in context
+ * @returns {Token|null} The Block comment
+ *   token containing the JSDoc comment for the given node or
+ *   null if not found.
+ * @public
+ */
+declare function getNonJsdocComment(
+  sourceCode: eslint.SourceCode,
+  node: eslint.Rule.Node,
+  settings: {
+    [name: string]: any;
+    maxLines: int;
+    minLines: int;
+  },
+): Token | null;
 /**
  * @param {(import('estree').Comment|import('eslint').Rule.Node) & {
  *   declaration?: any,
@@ -195,6 +217,7 @@ declare function getDecorator(
  *   the comment for.
  * @param {import('eslint').SourceCode} sourceCode
  * @param {{maxLines: int, minLines: int, [name: string]: any}} settings
+ * @param {{nonJSDoc?: boolean}} [opts]
  * @returns {Token|null} The Block comment token containing the JSDoc comment
  *    for the given node or null if not found.
  * @private
@@ -207,6 +230,9 @@ declare function findJSDocComment(
     maxLines: int;
     minLines: int;
   },
+  opts?: {
+    nonJSDoc?: boolean;
+  },
 ): Token | null;
 
 declare function hasSeeWithLink(spec: comment_parser.Spec): boolean;
@@ -311,6 +337,7 @@ export {
   findJSDocComment,
   getDecorator,
   getJSDocComment,
+  getNonJsdocComment,
   getReducedASTNode,
   getTokenizers,
   hasSeeWithLink,

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@es-joy/jsdoccomment",
-  "version": "0.43.1",
+  "version": "0.44.0",
   "author": "Brett Zamir <[email protected]>",
   "contributors": [],
   "description": "Maintained replacement for ESLint's deprecated SourceCode#getJSDocComment along with other jsdoc utilities",
@@ -31,7 +31,7 @@
     "lint": "npm run eslint --",
     "open": "open ./coverage/index.html",
     "prepublishOnly": "pnpm i && npm run build",
-    "test": "npm run lint && npm run build && vitest run --coverage",
+    "test": "npm run lint && npm run build && npm run test-ui",
     "test-ui": "vitest --ui --coverage",
     "tsc": "tsc",
     "types": "esm-d-ts gen ./src/index.js --output ./dist/index.d.ts"

src/jsdoccomment.js

@@ -274,11 +274,13 @@ const getReducedASTNode = function (node, sourceCode) {
  *   the comment for.
  * @param {import('eslint').SourceCode} sourceCode
  * @param {{maxLines: int, minLines: int, [name: string]: any}} settings
+ * @param {{nonJSDoc?: boolean}} [opts]
  * @returns {Token|null} The Block comment token containing the JSDoc comment
  *    for the given node or null if not found.
  * @private
  */
-const findJSDocComment = (astNode, sourceCode, settings) => {
+const findJSDocComment = (astNode, sourceCode, settings, opts = {}) => {
+  const {nonJSDoc} = opts;
   const {minLines, maxLines} = settings;
 
   /** @type {import('eslint').Rule.Node|import('estree').Comment} */
@@ -308,7 +310,7 @@ const findJSDocComment = (astNode, sourceCode, settings) => {
     if (!tokenBefore || !isCommentToken(tokenBefore)) {
       return null;
     }
-    if (tokenBefore.type === 'Line') {
+    if (!nonJSDoc && tokenBefore.type === 'Line') {
       currentNode = tokenBefore;
       continue;
     }
@@ -321,8 +323,12 @@ const findJSDocComment = (astNode, sourceCode, settings) => {
   }
 
   if (
-    tokenBefore.type === 'Block' &&
-    (/^\*\s/u).test(tokenBefore.value) &&
+    (
+      (nonJSDoc && (tokenBefore.type !== 'Block' ||
+        !(/^\*\s/u).test(tokenBefore.value))) ||
+      (!nonJSDoc && tokenBefore.type === 'Block' &&
+      (/^\*\s/u).test(tokenBefore.value))
+    ) &&
     currentNode.loc.start.line - (
       /** @type {import('eslint').AST.Token} */
       (parenthesisToken ?? tokenBefore)
@@ -357,6 +363,28 @@ const getJSDocComment = function (sourceCode, node, settings) {
   return findJSDocComment(reducedNode, sourceCode, settings);
 };
 
+/**
+ * Retrieves the comment preceding a given node.
+ *
+ * @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode
+ * @param {import('eslint').Rule.Node} node The AST node to get
+ *   the comment for.
+ * @param {{maxLines: int, minLines: int, [name: string]: any}} settings The
+ *   settings in context
+ * @returns {Token|null} The Block comment
+ *   token containing the JSDoc comment for the given node or
+ *   null if not found.
+ * @public
+ */
+const getNonJsdocComment = function (sourceCode, node, settings) {
+  const reducedNode = getReducedASTNode(node, sourceCode);
+
+  return findJSDocComment(reducedNode, sourceCode, settings, {
+    nonJSDoc: true
+  });
+};
+
 export {
-  getReducedASTNode, getJSDocComment, getDecorator, findJSDocComment
+  getReducedASTNode, getJSDocComment, getNonJsdocComment,
+  getDecorator, findJSDocComment
 };

test/jsdoccomment.test.js

@@ -3,8 +3,9 @@ import {traverse} from 'estraverse';
 import {SourceCode} from 'eslint';
 
 import {
-  getReducedASTNode
+  getReducedASTNode,
   // getJSDocComment, getDecorator, findJSDocComment
+  getNonJsdocComment
 } from '../src/index.js';
 
 const ESPREE_DEFAULT_CONFIG = {
@@ -56,3 +57,55 @@ describe('`getReducedASTNode`', function () {
     expect(parsed.type).to.equal('FunctionDeclaration');
   });
 });
+
+describe('`getComment`', function () {
+  it('gets line comment', function () {
+    const code = `// Test
+function quux () {}`;
+    const ast = parseAddingParents(code);
+    const sourceCode = new SourceCode(code, ast);
+
+    const comment = getNonJsdocComment(
+      sourceCode,
+      /** @type {import('eslint').Rule.Node} */ (ast.body[0]),
+      {
+        minLines: 0, maxLines: 1
+      }
+    );
+    expect(comment?.type).to.equal('Line');
+    expect(comment?.value).to.equal(' Test');
+  });
+
+  it('gets non-JSDoc multiline comments', function () {
+    const code = `/* Test */
+function quux () {}`;
+    const ast = parseAddingParents(code);
+    const sourceCode = new SourceCode(code, ast);
+
+    const comment = getNonJsdocComment(
+      sourceCode,
+      /** @type {import('eslint').Rule.Node} */ (ast.body[0]),
+      {
+        minLines: 0, maxLines: 1
+      }
+    );
+    expect(comment?.type).to.equal('Block');
+    expect(comment?.value).to.equal(' Test ');
+  });
+
+  it('ignores JSDoc multiline comments', function () {
+    const code = `/** Test */
+function quux () {}`;
+    const ast = parseAddingParents(code);
+    const sourceCode = new SourceCode(code, ast);
+
+    const comment = getNonJsdocComment(
+      sourceCode,
+      /** @type {import('eslint').Rule.Node} */ (ast.body[0]),
+      {
+        minLines: 0, maxLines: 1
+      }
+    );
+    expect(comment).to.equal(null);
+  });
+});