@es-joy/jsdoccomment - npm Package Compare versions

Comparing version 0.19.0 to 0.20.0

CHANGES.md

 # CHANGES for `@es-joy/jsdoccomment`
 
+## 0.20.0
+
+- fix: properly supports `name`/`postName` for multi-line type
+- fix: allow pratt parser to fail (unless empty)
+- fix: don't add tag postDelimiter when on 0 description line
+- fix: avoid adding extra line when only name and no succeeding description
+- docs: clarify re: `kind`
+- test: add `parsedType` with correct mode; add tests
+- chore: updates jsdoc-type-pratt-parser
+- chore: updates devDeps.
+
 ## 0.19.0
@@ -4,0 +15,0 @@

package.json

 {
   "name": "@es-joy/jsdoccomment",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "author": "Brett Zamir <[e-mail]>",
@@ -46,6 +46,6 @@ "contributors": [],
     "esquery": "^1.4.0",
-    "jsdoc-type-pratt-parser": "~2.2.2"
+    "jsdoc-type-pratt-parser": "~2.2.3"
   },
   "devDependencies": {
-    "@babel/core": "^7.17.2",
+    "@babel/core": "^7.17.4",
     "@babel/plugin-syntax-class-properties": "^7.12.13",
@@ -57,3 +57,3 @@ "@babel/preset-env": "^7.16.11",
     "chai": "^4.3.6",
-    "eslint": "^8.8.0",
+    "eslint": "^8.9.0",
     "eslint-config-ash-nazg": "32.3.0",
@@ -66,3 +66,3 @@ "eslint-config-standard": "^16.0.3",
     "eslint-plugin-import": "^2.25.4",
-    "eslint-plugin-jsdoc": "^37.8.2",
+    "eslint-plugin-jsdoc": "^37.9.1",
     "eslint-plugin-markdown": "^2.2.1",
@@ -75,6 +75,6 @@ "eslint-plugin-no-unsanitized": "^4.0.1",
     "eslint-plugin-unicorn": "^40.1.0",
-    "espree": "^9.3.0",
+    "espree": "^9.3.1",
     "estraverse": "^5.3.0",
     "mocha": "^9.2.0",
-    "rollup": "^2.67.1"
+    "rollup": "^2.67.2"
   },
@@ -86,7 +86,7 @@ "scripts": {
     "lint": "npm run eslint",
-    "mocha": "mocha --parallel --require chai/register-expect.js",
+    "mocha": "mocha --require chai/register-expect.js",
     "c8": "c8 npm run mocha",
     "test": "npm run lint && npm run rollup && npm run c8"
   },
-  "readme": "# @es-joy/jsdoccomment\n\n[![Node.js CI status](https://github.com/brettz9/getJSDocComment/workflows/Node.js%20CI/badge.svg)](https://github.com/brettz9/getJSDocComment/actions)\n\nThis project aims to preserve and expand upon the\n`SourceCode#getJSDocComment` functionality of the deprecated ESLint method.\n\nIt also exports a number of functions currently for working with JSDoc:\n\n## API\n\n### `parseComment`\n\nFor parsing `comment-parser` in a JSDoc-specific manner.\nMight wish to have tags with or without tags, etc. derived from a split off\nJSON file.\n\n### `commentParserToESTree`\n\nConverts [comment-parser](https://github.com/syavorsky/comment-parser)\nAST to ESTree/ESLint/Babel friendly AST. See the \"ESLint AST...\" section below.\n\n### `jsdocVisitorKeys`\n\nThe [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)\nfor `JsdocBlock`, `JsdocDescriptionLine`, and `JsdocTag`. More likely to be\nsubject to change or dropped in favor of another type parser.\n\n### `jsdocTypeVisitorKeys`\n\nJust a re-export of [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)\nfrom [`jsdoc-type-pratt-parser`](https://github.com/simonseyock/jsdoc-type-pratt-parser/).\n\n### `getDefaultTagStructureForMode`\n\nProvides info on JSDoc tags:\n\n- `nameContents` ('namepath-referencing'|'namepath-defining'|\n    'dual-namepath-referencing'|false) - Whether and how a name is allowed\n    following any type. Tags without a proper name (value `false`) may still\n    have a description (which can appear like a name); `descriptionAllowed`\n    in such cases would be `true`.\n    The presence of a truthy `nameContents` value is therefore only intended\n    to signify whether separate parsing should occur for a name vs. a\n    description, and what its nature should be.\n- `nameRequired` (boolean) - Whether a name must be present following any type.\n- `descriptionAllowed` (boolean) - Whether a description (following any name)\n    is allowed.\n- `typeAllowed` (boolean) - Whether the tag accepts a curly bracketed portion.\n    Even without a type, a tag may still have a name and/or description.\n- `typeRequired` (boolean) - Whether a curly bracketed type must be present.\n- `typeOrNameRequired` (boolean) - Whether either a curly bracketed type is\n    required or a name, but not necessarily both.\n\n### Miscellaneous\n\nAlso currently exports these utilities, though they might be removed in the\nfuture:\n\n- `getTokenizers` - Used with `parseComment` (its main core)\n- `toCamelCase` - Convert to CamelCase.\n- `hasSeeWithLink` - A utility to detect if a tag is `@see` and has a `@link`\n- `commentHandler` - Used by `eslint-plugin-jsdoc`. Might be removed in future.\n- `commentParserToESTree`- Converts [comment-parser](https://github.com/syavorsky/comment-parser)\n    AST to ESTree/ESLint/Babel friendly AST\n- `jsdocVisitorKeys` - The [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)\n    for `JSDocBlock`, `JSDocDescriptionLine`, and `JSDocTag`. Might change.\n- `jsdocTypeVisitorKeys` - [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)\n    for `jsdoc-type-pratt-parser`.\n- `getTokenizers` - A utility. Might be removed in future.\n- `toCamelCase` - A utility. Might be removed in future.\n- `hasSeeWithLink` - A utility to detect if a tag is `@see` and has a `@link`\n- `defaultNoTypes` = The tags which allow no types by default:\n    `default`, `defaultvalue`, `see`;\n- `defaultNoNames` - The tags which allow no names by default:\n    `access`, `author`, `default`, `defaultvalue`, `description`, `example`,\n    `exception`, `license`, `return`, `returns`, `since`, `summary`, `throws`,\n    `version`, `variation`\n\n## ESLint AST produced for `comment-parser` nodes (`JsdocBlock`, `JsdocTag`, and `JsdocDescriptionLine`)\n\nNote: Although not added in this package, `@es-joy/jsdoc-eslint-parser` adds\na `jsdoc` property to other ES nodes (using this project's `getJSDocComment`\nto determine the specific comment-block that will be attached as AST).\n\n### `JsdocBlock`\n\nHas two visitable properties:\n\n1. `tags` (an array of `JsdocTag`; see below)\n2. `descriptionLines` (an array of `JsdocDescriptionLine` for multiline\n    descriptions).\n\nHas the following custom non-visitable property:\n\n1. `lastDescriptionLine` - A number\n2. `endLine` - A number representing the line number with `end`\n\nMay also have the following non-visitable properties from `comment-parser`:\n\n1. `description` - Same as `descriptionLines` but as a string with newlines.\n2. `delimiter`\n3. `postDelimiter`\n4. `lineEnd`\n5. `end`\n\n### `JsdocTag`\n\nHas three visitable properties:\n\n1. `parsedType` (the `jsdoc-type-pratt-parser` AST representation of the tag's\n    type (see the `jsdoc-type-pratt-parser` section below)).\n2. `descriptionLines` (an array of `JsdocDescriptionLine` for multiline\n    descriptions)\n3. `typeLines` (an array of `JsdocTypeLine` for multiline type strings)\n\nMay also have the following non-visitable properties from `comment-parser`\n(note that all are included from `comment-parser` except `end` as that is only\nfor JSDoc blocks and note that `type` is renamed to `rawType`):\n\n1. `description` - Same as `descriptionLines` but as a string with newlines.\n2. `rawType` - `comment-parser` has this named as `type`, but because of a\n    conflict with ESTree using `type` for Node type, we renamed it to\n    `rawType`. It is otherwise the same as in `comment-parser`, i.e., a string\n    with newlines, though with the initial `{` and final `}` stripped out.\n    See `typeLines` for the array version of this property.\n3. `start`\n4. `delimiter`\n5. `postDelimiter`\n6. `tag` (this does differ from `comment-parser` now in terms of our stripping\n    the initial `@`)\n7. `postTag`\n8. `name`\n9. `postName`\n10. `postType`\n\n### `JsdocDescriptionLine`\n\nNo visitable properties.\n\nMay also have the following non-visitable properties from `comment-parser`:\n\n1. `delimiter`\n2. `postDelimiter`\n3. `start`\n4. `description`\n\n### `JsdocTypeLine`\n\nNo visitable properties.\n\nMay also have the following non-visitable properties from `comment-parser`:\n\n1. `delimiter`\n2. `postDelimiter`\n3. `start`\n4. `rawType` - Renamed from `comment-parser` to avoid a conflict. See\n    explanation under `JsdocTag`\n\n## ESLint AST produced for `jsdoc-type-pratt-parser`\n\nThe AST, including `type`, remains as is from [jsdoc-type-pratt-parser](https://github.com/simonseyock/jsdoc-type-pratt-parser/).\n\nThe type will always begin with a `JsdocType` prefix added, along with a\ncamel-cased type name, e.g., `JsdocTypeUnion`.\n\nThe `jsdoc-type-pratt-parser` visitor keys are also preserved without change.\n\n## Installation\n\n```shell\nnpm i @es-joy/jsdoccomment\n```\n\n## Changelog\n\nThe changelog can be found on the [CHANGES.md](./CHANGES.md).\n<!--## Contributing\n\nEveryone is welcome to contribute. Please take a moment to review the [contributing guidelines](CONTRIBUTING.md).\n-->\n## Authors and license\n\n[Brett Zamir](http://brett-zamir.me/) and\n[contributors](https://github.com/es-joy/jsdoc-eslint-parser/graphs/contributors).\n\nMIT License, see the included [LICENSE-MIT.txt](LICENSE-MIT.txt) file.\n\n## To-dos\n\n1. Get complete code coverage\n"
+  "readme": "# @es-joy/jsdoccomment\n\n[![Node.js CI status](https://github.com/brettz9/getJSDocComment/workflows/Node.js%20CI/badge.svg)](https://github.com/brettz9/getJSDocComment/actions)\n\nThis project aims to preserve and expand upon the\n`SourceCode#getJSDocComment` functionality of the deprecated ESLint method.\n\nIt also exports a number of functions currently for working with JSDoc:\n\n## API\n\n### `parseComment`\n\nFor parsing `comment-parser` in a JSDoc-specific manner.\nMight wish to have tags with or without tags, etc. derived from a split off\nJSON file.\n\n### `commentParserToESTree`\n\nConverts [comment-parser](https://github.com/syavorsky/comment-parser)\nAST to ESTree/ESLint/Babel friendly AST. See the \"ESLint AST...\" section below.\n\n### `jsdocVisitorKeys`\n\nThe [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)\nfor `JsdocBlock`, `JsdocDescriptionLine`, and `JsdocTag`. More likely to be\nsubject to change or dropped in favor of another type parser.\n\n### `jsdocTypeVisitorKeys`\n\nJust a re-export of [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)\nfrom [`jsdoc-type-pratt-parser`](https://github.com/simonseyock/jsdoc-type-pratt-parser/).\n\n### `getDefaultTagStructureForMode`\n\nProvides info on JSDoc tags:\n\n- `nameContents` ('namepath-referencing'|'namepath-defining'|\n    'dual-namepath-referencing'|false) - Whether and how a name is allowed\n    following any type. Tags without a proper name (value `false`) may still\n    have a description (which can appear like a name); `descriptionAllowed`\n    in such cases would be `true`.\n    The presence of a truthy `nameContents` value is therefore only intended\n    to signify whether separate parsing should occur for a name vs. a\n    description, and what its nature should be.\n- `nameRequired` (boolean) - Whether a name must be present following any type.\n- `descriptionAllowed` (boolean) - Whether a description (following any name)\n    is allowed.\n- `typeAllowed` (boolean) - Whether the tag accepts a curly bracketed portion.\n    Even without a type, a tag may still have a name and/or description.\n- `typeRequired` (boolean) - Whether a curly bracketed type must be present.\n- `typeOrNameRequired` (boolean) - Whether either a curly bracketed type is\n    required or a name, but not necessarily both.\n\n### Miscellaneous\n\nAlso currently exports these utilities, though they might be removed in the\nfuture:\n\n- `getTokenizers` - Used with `parseComment` (its main core)\n- `toCamelCase` - Convert to CamelCase.\n- `hasSeeWithLink` - A utility to detect if a tag is `@see` and has a `@link`\n- `commentHandler` - Used by `eslint-plugin-jsdoc`. Might be removed in future.\n- `commentParserToESTree`- Converts [comment-parser](https://github.com/syavorsky/comment-parser)\n    AST to ESTree/ESLint/Babel friendly AST\n- `jsdocVisitorKeys` - The [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)\n    for `JSDocBlock`, `JSDocDescriptionLine`, and `JSDocTag`. Might change.\n- `jsdocTypeVisitorKeys` - [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)\n    for `jsdoc-type-pratt-parser`.\n- `getTokenizers` - A utility. Might be removed in future.\n- `toCamelCase` - A utility. Might be removed in future.\n- `hasSeeWithLink` - A utility to detect if a tag is `@see` and has a `@link`\n- `defaultNoTypes` = The tags which allow no types by default:\n    `default`, `defaultvalue`, `see`;\n- `defaultNoNames` - The tags which allow no names by default:\n    `access`, `author`, `default`, `defaultvalue`, `description`, `example`,\n    `exception`, `kind`, `license`, `return`, `returns`, `since`, `summary`,\n    `throws`, `version`, `variation`\n\n## ESLint AST produced for `comment-parser` nodes (`JsdocBlock`, `JsdocTag`, and `JsdocDescriptionLine`)\n\nNote: Although not added in this package, `@es-joy/jsdoc-eslint-parser` adds\na `jsdoc` property to other ES nodes (using this project's `getJSDocComment`\nto determine the specific comment-block that will be attached as AST).\n\n### `JsdocBlock`\n\nHas two visitable properties:\n\n1. `tags` (an array of `JsdocTag`; see below)\n2. `descriptionLines` (an array of `JsdocDescriptionLine` for multiline\n    descriptions).\n\nHas the following custom non-visitable property:\n\n1. `lastDescriptionLine` - A number\n2. `endLine` - A number representing the line number with `end`\n\nMay also have the following non-visitable properties from `comment-parser`:\n\n1. `description` - Same as `descriptionLines` but as a string with newlines.\n2. `delimiter`\n3. `postDelimiter`\n4. `lineEnd`\n5. `end`\n\n### `JsdocTag`\n\nHas three visitable properties:\n\n1. `parsedType` (the `jsdoc-type-pratt-parser` AST representation of the tag's\n    type (see the `jsdoc-type-pratt-parser` section below)).\n2. `descriptionLines` (an array of `JsdocDescriptionLine` for multiline\n    descriptions)\n3. `typeLines` (an array of `JsdocTypeLine` for multiline type strings)\n\nMay also have the following non-visitable properties from `comment-parser`\n(note that all are included from `comment-parser` except `end` as that is only\nfor JSDoc blocks and note that `type` is renamed to `rawType`):\n\n1. `description` - Same as `descriptionLines` but as a string with newlines.\n2. `rawType` - `comment-parser` has this named as `type`, but because of a\n    conflict with ESTree using `type` for Node type, we renamed it to\n    `rawType`. It is otherwise the same as in `comment-parser`, i.e., a string\n    with newlines, though with the initial `{` and final `}` stripped out.\n    See `typeLines` for the array version of this property.\n3. `start`\n4. `delimiter`\n5. `postDelimiter`\n6. `tag` (this does differ from `comment-parser` now in terms of our stripping\n    the initial `@`)\n7. `postTag`\n8. `name`\n9. `postName`\n10. `postType`\n\n### `JsdocDescriptionLine`\n\nNo visitable properties.\n\nMay also have the following non-visitable properties from `comment-parser`:\n\n1. `delimiter`\n2. `postDelimiter`\n3. `start`\n4. `description`\n\n### `JsdocTypeLine`\n\nNo visitable properties.\n\nMay also have the following non-visitable properties from `comment-parser`:\n\n1. `delimiter`\n2. `postDelimiter`\n3. `start`\n4. `rawType` - Renamed from `comment-parser` to avoid a conflict. See\n    explanation under `JsdocTag`\n\n## ESLint AST produced for `jsdoc-type-pratt-parser`\n\nThe AST, including `type`, remains as is from [jsdoc-type-pratt-parser](https://github.com/simonseyock/jsdoc-type-pratt-parser/).\n\nThe type will always begin with a `JsdocType` prefix added, along with a\ncamel-cased type name, e.g., `JsdocTypeUnion`.\n\nThe `jsdoc-type-pratt-parser` visitor keys are also preserved without change.\n\n## Installation\n\n```shell\nnpm i @es-joy/jsdoccomment\n```\n\n## Changelog\n\nThe changelog can be found on the [CHANGES.md](./CHANGES.md).\n<!--## Contributing\n\nEveryone is welcome to contribute. Please take a moment to review the [contributing guidelines](CONTRIBUTING.md).\n-->\n## Authors and license\n\n[Brett Zamir](http://brett-zamir.me/) and\n[contributors](https://github.com/es-joy/jsdoc-eslint-parser/graphs/contributors).\n\nMIT License, see the included [LICENSE-MIT.txt](LICENSE-MIT.txt) file.\n\n## To-dos\n\n1. Get complete code coverage\n"
 }

README.md

@@ -77,4 +77,4 @@ # @es-joy/jsdoccomment
     `access`, `author`, `default`, `defaultvalue`, `description`, `example`,
-    `exception`, `license`, `return`, `returns`, `since`, `summary`, `throws`,
-    `version`, `variation`
+    `exception`, `kind`, `license`, `return`, `returns`, `since`, `summary`,
+    `throws`, `version`, `variation`
 
@@ -81,0 +81,0 @@ ## ESLint AST produced for `comment-parser` nodes (`JsdocBlock`, `JsdocTag`, and `JsdocDescriptionLine`)

src/commentParserToESTree.js

@@ -42,6 +42,5 @@ import {parse as jsdocTypePrattParse} from 'jsdoc-type-pratt-parser';
   let parsedType = null;
-  try {
+
+  if (lastTag.rawType) {
     parsedType = jsdocTypePrattParse(lastTag.rawType, mode);
-  } catch {
-    // Ignore
   }
@@ -127,2 +126,3 @@
 
+  const endLine = source.length - 1;
   const ast = {
@@ -136,3 +136,3 @@ delimiter: delimiterRoot,
     end: endRoot,
-    endLine: source.length - 1,
+    endLine,
     postDelimiter: postDelimiterRoot,
@@ -181,7 +181,27 @@ lineEnd: lineEndRoot,
         end: ed,
+        delimiter: de,
+        postDelimiter: pd,
         ...tkns
       } = tokens;
 
+      if (!tokens.name) {
+        let i = 0;
+        while (source[idx + i]) {
+          const {tokens: {
+            name,
+            postName
+          }} = source[idx + i];
+          if (name) {
+            tkns.name = name;
+            tkns.postName = postName;
+            break;
+          }
+          i++;
+        }
+      }
+
       const tagObj = {
         ...tkns,
+        postDelimiter: lastDescriptionLine ? pd : '',
+        delimiter: lastDescriptionLine ? de : '',
         descriptionLines: [],
@@ -202,11 +222,19 @@ rawType: '',
       lastTag.typeLines.push(
-        {
-          delimiter,
-          postDelimiter,
-          rawType,
-          start,
-          type: 'JsdocTypeLine'
-        }
+        lastTag.typeLines.length
+          ? {
+            delimiter,
+            postDelimiter,
+            rawType,
+            start,
+            type: 'JsdocTypeLine'
+          }
+          : {
+            delimiter: '',
+            postDelimiter: '',
+            rawType,
+            start: '',
+            type: 'JsdocTypeLine'
+          }
       );
-      lastTag.rawType += rawType;
+      lastTag.rawType += lastTag.rawType ? '\n' + rawType : rawType;
     }
@@ -216,9 +244,19 @@
       const holder = lastTag || ast;
-      holder.descriptionLines.push({
-        delimiter,
-        description,
-        postDelimiter,
-        start,
-        type: 'JsdocDescriptionLine'
-      });
+      holder.descriptionLines.push(
+        holder.descriptionLines.length
+          ? {
+            delimiter,
+            description,
+            postDelimiter,
+            start,
+            type: 'JsdocDescriptionLine'
+          }
+          : {
+            delimiter: '',
+            description,
+            postDelimiter: '',
+            start: '',
+            type: 'JsdocDescriptionLine'
+          }
+      );
       holder.description += holder.description
@@ -244,8 +282,8 @@ ? '\n' + description
 const jsdocVisitorKeys = {
-  JsdocBlock: ['tags', 'descriptionLines'],
+  JsdocBlock: ['descriptionLines', 'tags'],
   JsdocDescriptionLine: [],
   JsdocTypeLine: [],
-  JsdocTag: ['descriptionLines', 'typeLines', 'parsedType']
+  JsdocTag: ['parsedType', 'typeLines', 'descriptionLines']
 };
 
 export {commentParserToESTree, jsdocVisitorKeys};

src/index.js

@@ -14,1 +14,3 @@ export {visitorKeys as jsdocTypeVisitorKeys} from 'jsdoc-type-pratt-parser';
 export * from './jsdoccomment.js';
+
+export {default as estreeToString} from './estreeToString.js';

No alert changes

Improved metrics

Total package byte prevSize

66448

increased by12.53%

Number of package files

16

increased by6.67%

Lines of code

1433

increased by18.72%

Dependency changes

• Updatedjsdoc-type-pratt-parser@~2.2.3