@es-joy/jsdoccomment - npm Package Compare versions

Comparing version 0.7.2 to 0.8.0-alpha.1

CHANGES.md

 # CHANGES for `@es-joy/jsdoccomment`
 
+## 0.8.0
+
+- Breaking change: Export globally as `JsdocComment`
+- Breaking change: Change `JSDoc` prefixes of all node types to `Jsdoc`
+- Breaking change: Drop `jsdoctypeparserToESTree`
+- Breaking enhancement: Switch to `jsdoc-type-pratt-parser` (toward greater
+    TypeScript expressivity and compatibility/support with catharsis)
+- Enhancement: Export `jsdocTypeVisitorKeys` (from `jsdoc-type-pratt-parser`)
+
 ## 0.7.2
@@ -4,0 +13,0 @@

package.json

 {
-  "name": "@es-joy/jsdoccomment",
-  "version": "0.7.2",
-  "author": "Brett Zamir <[e-mail]>",
-  "contributors": [],
-  "description": "Maintained replacement for ESLint's deprecated SourceCode#getJSDocComment",
-  "license": "MIT",
-  "keywords": [
-    "eslint",
-    "sourcecode"
-  ],
-  "type": "module",
-  "main": "./dist/index.cjs.cjs",
-  "exports": {
-    "require": "./dist/index.cjs.cjs",
-    "import": "./src/index.js"
-  },
-  "c8": {
-    "checkCoverage": true,
-    "branches": 100,
-    "statements": 100,
-    "lines": 100,
-    "functions": 100
-  },
-  "browserslist": [
-    "cover 100%"
-  ],
-  "scripts": {
-    "prepublishOnly": "npm run rollup",
-    "rollup": "rollup -c",
-    "eslint": "eslint --ext=jd,md,html",
-    "lint": "npm run eslint",
-    "mocha": "mocha --require chai/register-expect",
-    "c8": "c8 npm run mocha",
-    "test": "npm run lint && npm run rollup && npm run c8"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/brettz9/getJSDocComment.git"
-  },
-  "bugs": {
-    "url": "https://github.com/brettz9/getJSDocComment/issues"
-  },
-  "homepage": "https://github.com/brettz9/getJSDocComment",
-  "engines": {
-    "node": ">=10.0.0"
-  },
-  "dependencies": {
-    "comment-parser": "^1.1.5",
-    "esquery": "^1.4.0",
-    "jsdoctypeparser": "^9.0.0"
-  },
-  "devDependencies": {
-    "@babel/core": "^7.14.0",
-    "@babel/plugin-syntax-class-properties": "^7.12.13",
-    "@babel/preset-env": "^7.14.0",
-    "@brettz9/eslint-plugin": "^1.0.3",
-    "@rollup/plugin-babel": "^5.3.0",
-    "c8": "^7.7.1",
-    "chai": "^4.3.4",
-    "eslint": "^7.25.0",
-    "eslint-config-ash-nazg": "29.12.1",
-    "eslint-config-standard": "^16.0.2",
-    "eslint-plugin-array-func": "^3.1.7",
-    "eslint-plugin-compat": "^3.9.0",
-    "eslint-plugin-eslint-comments": "^3.2.0",
-    "eslint-plugin-html": "^6.1.2",
-    "eslint-plugin-import": "^2.22.1",
-    "eslint-plugin-jsdoc": "^32.3.1",
-    "eslint-plugin-markdown": "^2.0.1",
-    "eslint-plugin-no-unsanitized": "^3.1.5",
-    "eslint-plugin-no-use-extend-native": "^0.5.0",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^5.1.0",
-    "eslint-plugin-radar": "^0.2.1",
-    "eslint-plugin-unicorn": "^31.0.0",
-    "mocha": "^8.3.2",
-    "rollup": "^2.46.0"
-  }
+	"name": "@es-joy/jsdoccomment",
+	"version": "0.8.0-alpha.1",
+	"author": "Brett Zamir <[e-mail]>",
+	"contributors": [],
+	"description": "Maintained replacement for ESLint's deprecated SourceCode#getJSDocComment",
+	"license": "MIT",
+	"keywords": [
+		"eslint",
+		"sourcecode"
+	],
+	"type": "module",
+	"main": "./dist/index.cjs.cjs",
+	"exports": {
+		"require": "./dist/index.cjs.cjs",
+		"import": "./src/index.js"
+	},
+	"c8": {
+		"checkCoverage": true,
+		"branches": 100,
+		"statements": 100,
+		"lines": 100,
+		"functions": 100
+	},
+	"browserslist": [
+		"cover 100%"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/brettz9/getJSDocComment.git"
+	},
+	"bugs": {
+		"url": "https://github.com/brettz9/getJSDocComment/issues"
+	},
+	"homepage": "https://github.com/brettz9/getJSDocComment",
+	"engines": {
+		"node": ">=10.0.0"
+	},
+	"dependencies": {
+		"comment-parser": "^1.1.5",
+		"esquery": "^1.4.0",
+		"jsdoc-type-pratt-parser": "1.0.0-alpha.23"
+	},
+	"devDependencies": {
+		"@babel/core": "^7.14.0",
+		"@babel/plugin-syntax-class-properties": "^7.12.13",
+		"@babel/preset-env": "^7.14.0",
+		"@brettz9/eslint-plugin": "^1.0.3",
+		"@rollup/plugin-babel": "^5.3.0",
+		"c8": "^7.7.1",
+		"chai": "^4.3.4",
+		"eslint": "^7.25.0",
+		"eslint-config-ash-nazg": "29.12.1",
+		"eslint-config-standard": "^16.0.2",
+		"eslint-plugin-array-func": "^3.1.7",
+		"eslint-plugin-compat": "^3.9.0",
+		"eslint-plugin-eslint-comments": "^3.2.0",
+		"eslint-plugin-html": "^6.1.2",
+		"eslint-plugin-import": "^2.22.1",
+		"eslint-plugin-jsdoc": "^32.3.1",
+		"eslint-plugin-markdown": "^2.0.1",
+		"eslint-plugin-no-unsanitized": "^3.1.5",
+		"eslint-plugin-no-use-extend-native": "^0.5.0",
+		"eslint-plugin-node": "^11.1.0",
+		"eslint-plugin-promise": "^5.1.0",
+		"eslint-plugin-radar": "^0.2.1",
+		"eslint-plugin-unicorn": "^31.0.0",
+		"mocha": "^8.3.2",
+		"rollup": "^2.46.0"
+	},
+	"scripts": {
+		"rollup": "rollup -c",
+		"eslint": "eslint --ext=jd,md,html",
+		"lint": "npm run eslint",
+		"mocha": "mocha --require chai/register-expect",
+		"c8": "c8 npm run mocha",
+		"test": "npm run lint && npm run rollup && npm run c8"
+	}
 }

README.md

@@ -10,14 +10,62 @@ # @es-joy/jsdoccomment
 
-- `parseComment` - For parsing `comment-parser` in a JSDoc-specific manner.
-    Might wish to have tags with or without tags, etc. derived from a split off
-    JSON file.
+## API
+
+### `parseComment`
+
+For parsing `comment-parser` in a JSDoc-specific manner.
+Might wish to have tags with or without tags, etc. derived from a split off
+JSON file.
+
+### `commentParserToESTree`
+
+Converts [comment-parser](https://github.com/syavorsky/comment-parser)
+AST to ESTree/ESLint/Babel friendly AST. See the "ESLint AST..." section below.
+
+### `jsdocVisitorKeys`
+
+The [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)
+for `JsdocBlock`, `JsdocDescriptionLine`, and `JsdocTag`. More likely to be
+subject to change or dropped in favor of another type parser.
+
+### `jsdocTypeVisitorKeys`
+
+Just a re-export of [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)
+from [`jsdoc-type-pratt-parser`](https://github.com/simonseyock/jsdoc-type-pratt-parser/).
+
+### `getDefaultTagStructureForMode`
+
+Provides info on JSDoc tags:
+
+- `nameContents` ('namepath-referencing'|'namepath-defining'|
+    'dual-namepath-referencing'|false) - Whether and how a name is allowed
+    following any type. Tags without a proper name (value `false`) may still
+    have a description (which can appear like a name); `descriptionAllowed`
+    in such cases would be `true`.
+    The presence of a truthy `nameContents` value is therefore only intended
+    to signify whether separate parsing should occur for a name vs. a
+    description, and what its nature should be.
+- `nameRequired` (boolean) - Whether a name must be present following any type.
+- `descriptionAllowed` (boolean) - Whether a description (following any name)
+    is allowed.
+- `typeAllowed` (boolean) - Whether the tag accepts a curly bracketed portion.
+    Even without a type, a tag may still have a name and/or description.
+- `typeRequired` (boolean) - Whether a curly bracketed type must be present.
+- `typeOrNameRequired` (boolean) - Whether either a curly bracketed type is
+    required or a name, but not necessarily both.
+
+### Miscellaneous
+
+Also currently exports these utilities, though they might be removed in the
+future:
+
+- `getTokenizers` - Used with `parseComment` (its main core)
+- `toCamelCase` - Convert to CamelCase.
+- `hasSeeWithLink` - A utility to detect if a tag is `@see` and has a `@link`
 - `commentHandler` - Used by `eslint-plugin-jsdoc`. Might be removed in future.
 - `commentParserToESTree`- Converts [comment-parser](https://github.com/syavorsky/comment-parser)
     AST to ESTree/ESLint/Babel friendly AST
-- `jsdoctypeparserToESTree`- Converts [jsdoctypeparser](https://github.com/jsdoctypeparser/jsdoctypeparser)
-    AST to ESTree/ESLint/Babel friendly AST
 - `jsdocVisitorKeys` - The [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)
     for `JSDocBlock`, `JSDocDescriptionLine`, and `JSDocTag`. Might change.
 - `jsdocTypeVisitorKeys` - [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)
-    for jsdoctypeparser. More likely to be subject to change.
+    for `jsdoc-type-pratt-parser`.
 - `getTokenizers` - A utility. Might be removed in future.
@@ -33,3 +81,3 @@ - `toCamelCase` - A utility. Might be removed in future.
 
-## ESLint AST produced for `comment-parser` nodes (`JSDocBlock`, `JSDocTag`, and `JSDocDescriptionLine`)
+## ESLint AST produced for `comment-parser` nodes (`JsdocBlock`, `JsdocTag`, and `JsdocDescriptionLine`)
 
@@ -40,8 +88,8 @@ Note: Although not added in this package, `@es-joy/jsdoc-eslint-parser` adds
 
-### `JSDocBlock`
+### `JsdocBlock`
 
 Has two visitable properties:
 
-1. `tags` (an array of `JSDocTag`; see below)
-2. `descriptionLines` (an array of `JSDocDescriptionLine` for multiline
+1. `tags` (an array of `JsdocTag`; see below)
+2. `descriptionLines` (an array of `JsdocDescriptionLine` for multiline
     descriptions).
@@ -60,11 +108,11 @@
 
-### `JSDocTag`
+### `JsdocTag`
 
 Has three visitable properties:
 
-1. `parsedType` (the `jsdoctypeparser` AST representaiton of the tag's
-    type (see the `jsdoctypeparser` section below)).
-2. `descriptionLines`' (an array of `JSDocDescriptionLine` for multiline
+1. `parsedType` (the `jsdoc-type-pratt-parser` AST representaiton of the tag's
+    type (see the `jsdoc-type-pratt-parser` section below)).
+2. `descriptionLines`' (an array of `JsdocDescriptionLine` for multiline
     descriptions)
-3. `typeLines` (an array of `JSDocTypeLine` for multiline type strings)
+3. `typeLines` (an array of `JsdocTypeLine` for multiline type strings)
 
@@ -92,3 +140,3 @@ May also have the following non-visitable properties from `comment-parser`
 
-### `JSDocDescriptionLine`
+### `JsdocDescriptionLine`
 
@@ -104,3 +152,3 @@ No visitable properties.
 
-### `JSDocTypeLine`
+### `JsdocTypeLine`
 
@@ -115,16 +163,12 @@ No visitable properties.
 4. `rawType` - Renamed from `comment-parser` to avoid a conflict. See
-    explanation under `JSDocTag`
+    explanation under `JsdocTag`
 
-## ESLint AST produced for `jsdoctypeparser`
+## ESLint AST produced for `jsdoc-type-pratt-parser`
 
-The `type` has been changed for the type AST. Relative to `jsdoctypeparser`
-nodes, the type will have a `JSDocType` prefix added plus a camel-casing of the
-old type name, so, e.g., `INSTANCE_MEMBER` will become
-`JSDocTypeInstanceMember`.
-See [jsdoctypeparser](https://github.com/jsdoctypeparser/jsdoctypeparser)
-for the current list of node types which are transformed in this manner.
+The AST, including `type`, remains as is from [jsdoc-type-pratt-parser](https://github.com/simonseyock/jsdoc-type-pratt-parser/).
 
-Otherwise, the node properties are as in `jsdoctypeparser`.
+The type will always begin with a `JsdocType` prefix added, along with a
+camel-cased type name, e.g., `JsdocTypeUnion`.
 
-The `jsdoctypeparser` visitor keys are also modified accordingly.
+The `jsdoc-type-pratt-parser` visitor keys are also preserved without change.
 
@@ -154,3 +198,1 @@ ## Installation
 1. Get complete code coverage
-2. If `comment-parser` (and `jsdoctypeparser`) are not exporting proper
-    ESLint AST, then provide simple utilities to convert their AST

src/commentHandler.js

 import esquery from 'esquery';
 
 import {
+  visitorKeys as jsdocTypePrattParserVisitorKeys
+} from 'jsdoc-type-pratt-parser';
+
+import {
   commentParserToESTree, jsdocVisitorKeys
 } from './commentParserToESTree.js';
-import {
-  jsdocTypeVisitorKeys
-} from './jsdoctypeparserToESTree.js';
 
@@ -34,3 +35,3 @@ /**
       visitorKeys: {
-        ...jsdocTypeVisitorKeys,
+        ...jsdocTypePrattParserVisitorKeys,
         ...jsdocVisitorKeys
@@ -37,0 +38,0 @@ }

src/commentParserToESTree.js

@@ -1,7 +0,3 @@
-import {parse as jsdoctypeParse} from 'jsdoctypeparser';
+import {parse as jsdocTypePrattParse} from 'jsdoc-type-pratt-parser';
 
-import {
-  jsdoctypeparserToESTree
-} from './jsdoctypeparserToESTree.js';
-
 const stripEncapsulatingBrackets = (container, isArr) => {
@@ -41,3 +37,3 @@ if (isArr) {
 
-    type: 'JSDocBlock'
+    type: 'JsdocBlock'
   };
@@ -75,3 +71,3 @@
         try {
-          parsedType = jsdoctypeParse(lastTag.rawType, {mode});
+          parsedType = jsdocTypePrattParse(lastTag.rawType, mode);
         } catch {
@@ -81,3 +77,3 @@ // Ignore
 
-        lastTag.parsedType = jsdoctypeparserToESTree(parsedType);
+        lastTag.parsedType = parsedType;
       }
@@ -100,3 +96,3 @@
         rawType: '',
-        type: 'JSDocTag',
+        type: 'JsdocTag',
         typeLines: []
@@ -119,3 +115,3 @@ };
           start,
-          type: 'JSDocTypeLine'
+          type: 'JsdocTypeLine'
         }
@@ -133,3 +129,3 @@ );
         start,
-        type: 'JSDocDescriptionLine'
+        type: 'JsdocDescriptionLine'
       });
@@ -149,8 +145,8 @@ holder.description += holder.description
 const jsdocVisitorKeys = {
-  JSDocBlock: ['tags', 'descriptionLines'],
-  JSDocDescriptionLine: [],
-  JSDocTypeLine: [],
-  JSDocTag: ['descriptionLines', 'typeLines', 'parsedType']
+  JsdocBlock: ['tags', 'descriptionLines'],
+  JsdocDescriptionLine: [],
+  JsdocTypeLine: [],
+  JsdocTag: ['descriptionLines', 'typeLines', 'parsedType']
 };
 
 export {commentParserToESTree, jsdocVisitorKeys};

src/index.js

@@ -0,1 +1,3 @@
+export {visitorKeys as jsdocTypeVisitorKeys} from 'jsdoc-type-pratt-parser';
+
 export {default as commentHandler} from './commentHandler.js';
@@ -9,4 +11,2 @@
 
-export * from './jsdoctypeparserToESTree.js';
-
 export * from './jsdoccomment.js';

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

Found 1 instance in 1 package

Improved metrics

Number of lines in readme file

191

increased by28.19%

Worsened metrics

Total package byte prevSize

43436

decreased by-2.19%

Number of package files

15

decreased by-6.25%

Lines of code

1001

decreased by-8.92%

Dependency changes

• + Addedjsdoc-type-pratt-parser@1.0.0-alpha.23

• + Addedjsdoc-type-pratt-parser@1.0.0-alpha.23(transitive)

• - Removedjsdoctypeparser@^9.0.0

• - Removedjsdoctypeparser@9.0.0(transitive)