From 2691222b650a76bb90893c22d82b654f3cc7e4d5 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 25 Apr 2022 07:19:21 -0700 Subject: [PATCH] tools: bump jsdoccomment from 0.22.1 to 0.29.0 A bug in jsdoccomment 0.28.0 forced us to pin to an earlier version. The bug has been fixed now, so we can update. Refs: https://github.com/es-joy/jsdoccomment/issues/8 PR-URL: https://github.com/nodejs/node/pull/42857 Reviewed-By: Darshan Sen Reviewed-By: Mohammed Keyvanzadeh --- .../@es-joy/jsdoccomment/.editorconfig | 15 - .../@es-joy/jsdoccomment/.eslintignore | 4 - .../@es-joy/jsdoccomment/.eslintrc.cjs | 31 -- .../@es-joy/jsdoccomment/CHANGES.md | 355 ------------------ .../@es-joy/jsdoccomment/README.md | 191 ---------- .../@es-joy/jsdoccomment/dist/index.cjs.cjs | 121 ++++-- .../@es-joy/jsdoccomment/package.json | 30 +- .../jsdoccomment/src/commentParserToESTree.js | 63 ++-- .../jsdoccomment/src/estreeToString.js | 61 +-- .../@es-joy/jsdoccomment/src/jsdoccomment.js | 12 + .../@es-joy/jsdoccomment/src/parseComment.js | 12 +- .../eslint/node_modules/browserslist/index.js | 1 + .../node_modules/browserslist/package.json | 8 +- .../eslint-plugin-jsdoc/package.json | 8 +- 14 files changed, 202 insertions(+), 710 deletions(-) delete mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.editorconfig delete mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintignore delete mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintrc.cjs delete mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/CHANGES.md delete mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/README.md diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.editorconfig b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.editorconfig deleted file mode 100644 index ff45b8651f9a06..00000000000000 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.editorconfig +++ /dev/null @@ -1,15 +0,0 @@ -; EditorConfig file: https://EditorConfig.org -; Install the "EditorConfig" plugin into your editor to use - -root = true - -[*] -charset = utf-8 -end_of_line = lf -insert_final_newline = true -indent_style = space -indent_size = 2 -trim_trailing_whitespace = true - -[*.md] -indent_size = 4 diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintignore b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintignore deleted file mode 100644 index 132e9461546f2a..00000000000000 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintignore +++ /dev/null @@ -1,4 +0,0 @@ -coverage -node_modules -dist -!.*.js diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintrc.cjs b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintrc.cjs deleted file mode 100644 index ce02e48c878103..00000000000000 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintrc.cjs +++ /dev/null @@ -1,31 +0,0 @@ -'use strict'; - -module.exports = { - extends: [ - 'ash-nazg/sauron-node-overrides' - ], - settings: { - polyfills: [ - 'console', - 'Error', - 'Set' - ] - }, - overrides: [ - { - files: 'test/**' - } - ], - - // Auto-set dynamically by config but needs to be explicit for Atom - parserOptions: { - ecmaVersion: 2021 - }, - - rules: { - // Reenable after this is addressed: https://github.com/eslint/eslint/issues/14745 - 'jsdoc/check-examples': 'off', - // https://github.com/benmosher/eslint-plugin-import/issues/1868 - 'import/no-unresolved': 'off' - } -}; diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/CHANGES.md b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/CHANGES.md deleted file mode 100644 index ae33b447ec6a48..00000000000000 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/CHANGES.md +++ /dev/null @@ -1,355 +0,0 @@ -# CHANGES for `@es-joy/jsdoccomment` - -## 0.22.1 - -- fix: ensure `getJSDocComment` does not treat block comments as JSDoc unless - their first asterisk is followed by whitespace - -## 0.22.0 - -- fix: update dep. `jsdoc-type-pratt-parser` -- chore: update `comment-parser` and simplify as possible - -## 0.21.2 - -- fix: only throw if the raw type is not empty - -## 0.21.1 - -- fix: provide clearer error message for `throwOnTypeParsingErrors` - -## 0.21.0 - -- feat: add `throwOnTypeParsingErrors` to receive run-time type parsing errors - for `parsedType` -- chore: update jsdoc-type-pratt-parser and devDeps.; also lints - -## 0.20.1 - -- fix: resume catching bad parsed type (at least until - `jsdoc-type-pratt-parser` may support all expected types) - -## 0.20.0 - -- feat: add estree stringifer -- 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 - -### User-impacting - -- feat: treat `@kind` as having no name - -### Dev-impacting - -- docs: jsdoc -- test: begin checking `jsdoccomment` -- test: adds lcov reporter and open script for it -- chore: update devDeps. - -## 0.18.0 - -### User-impacting - -- feat: add non-visitable `endLine` property (so can detect line number - when no description present) -- feat: supply `indent` default for `parseComment` -- fix: ensure `postName` gets a space for `@template` with a description -- fix: converting JSDoc comment with tag on same line as end (e.g., single - line) to AST -- chore: update `jsdoc-type-pratt-parser` - -### Dev-impacting - -- docs: add jsdoc blocks internally -- chore: update devDeps. -- test: avoid need for `expect` -- test: complete coverage for `commentHandler`, `parseComment` tests - -## 0.17.0 - -### User-impacting - -- Enhancement: Re-export `jsdoc-type-pratt-parser` -- Update: `jsdoc-type-pratt-parser` to 2.2.1 - -### Dev-impacting - -- npm: Update devDeps. - -## 0.16.0 - -### User-impacting - -- Update: `jsdoc-type-pratt-parser` to 2.2.0 - -### Dev-impacting - -- npm: Update devDeps. - -## 0.15.0 - -### User-impacting - -- Update: `jsdoc-type-pratt-parser` to 2.1.0 - -### Dev-impacting - -- npm: Update devDeps. - -## 0.14.2 - -### User-impacting - -- Fix: Find comments previous to parentheses (used commonly in TypeScript) - -### Dev-impacting - -- npm: Update devDeps. - -## 0.14.1 - -### User-impacting - -- Update: `jsdoc-type-pratt-parser` to 2.0.2 - -## 0.14.0 - -### User-impacting - -- Update: `jsdoc-type-pratt-parser` to 2.0.1 - -### Dev-impacting - -- npm: Update devDeps. - -## 0.13.0 - -### User-impacting - -- Update: `comment-parser` to 1.3.0 -- Fix: Allow comment on `ExportDefaultDeclaration` - -## 0.12.0 - -### User-impacting - -- Update: `jsdoc-type-pratt-parser` to 2.0.0 -- Enhancement: Support Node 17 (@timgates42) -- Docs: Typo (@timgates42) - -### Dev-impacting - -- Linting: As per latest ash-nazg -- npm: Update devDeps. - -## 0.11.0 - -- Update: For `@typescript/eslint-parser@5`, add `PropertyDefinition` - -## 0.10.8 - -### User-impacting - -- npm: Liberalize `engines` as per `comment-parser` change -- npm: Bump `comment-parser` - -### Dev-impacting - -- Linting: As per latest ash-nazg -- npm: Update devDeps. - -## 0.10.7 - -- npm: Update comment-parser with CJS fix and re-exports -- npm: Update devDeps. - -## 0.10.6 - -- Fix: Ensure copying latest build of `comment-parser`'s ESM utils - -## 0.10.5 - -- npm: Bump fixed `jsdoc-type-pratt-parser` and devDeps. - -## 0.10.4 - -- Fix: Bundle `comment-parser` nested imports so that IDEs (like Atom) - bundling older Node versions can still work. Still mirroring the - stricter `comment-parser` `engines` for now, however. - -## 0.10.3 - -- npm: Avoid exporting nested subpaths for sake of older Node versions - -## 0.10.2 - -- npm: Specify exact supported range: `^12.20 || ^14.14.0 || ^16` - -## 0.10.1 - -- npm: Apply patch version of `comment-parser` - -## 0.10.0 - -- npm: Point to stable `comment-parser` - -## 0.9.0-alpha.6 - -### User-impacting - -- Update: For `comment-parser` update, add `lineEnd` - -## 0.9.0-alpha.5 - -### User-impacting - -- npm: Bump `comment-parser` (for true ESM) -- Update: Remove extensions for packages for native ESM in `comment-parser` fix - -### Dev-impacting - -- npm: Update devDeps. - -## 0.9.0-alpha.4 - -- Docs: Update repo info in `package.json` - -## 0.9.0-alpha.3 - -- Fix: Due to `comment-parser` still needing changes, revert for now to alpha.1 - -## 0.9.0-alpha.2 - -### User-impacting - -- npm: Bump `comment-parser` (for true ESM) -- Update: Remove extensions for packages for native ESM in `comment-parser` fix - -### Dev-impacting - -- npm: Update devDeps. - -## 0.9.0-alpha.1 - -### User-impacting - -- Breaking change: Indicate minimum for `engines` as Node >= 12 -- npm: Bump `comment-parser` - -### Dev-impacting - -- npm: Lint cjs files -- npm: Fix eslint script -- npm: Update devDeps. - -## 0.8.0 - -### User-impacting - -- npm: Update `jsdoc-type-pratt-parser` (prerelease to stable patch) - -### Dev-impacting - -- npm: Update devDeps. - -## 0.8.0-alpha.2 - -- Fix: Avoid erring with missing `typeLines` - -## 0.8.0-alpha.1 - -- 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 - -- Fix: Add `@description` to `noNames` - -## 0.7.1 - -- Fix: Add `@summary` to `noNames` - -## 0.7.0 - -- Enhancement: Allow specifying `noNames` and `noTypes` on `parseComment` - to override (or add to) tags which should have no names or types. -- Enhancement: Export `hasSeeWithLink` utility and `defaultNoTypes` and - `defaultNoNames`. - -## 0.6.0 - -- Change `comment-parser` `tag` AST to avoid initial `@` - -## 0.5.1 - -- Fix: Avoid setting `variation` name (just the description) (including in - dist) -- npm: Add `prepublishOnly` script - -## 0.5.0 - -- Fix: Avoid setting `variation` name (just the description) - -## 0.4.4 - -- Fix: Avoid setting `name` and `description` for simple `@template SomeName` - -## 0.4.3 - -- npm: Ignores Github file - -## 0.4.2 - -- Fix: Ensure replacement of camel-casing (used in `jsdoctypeparser` nodes and - visitor keys is global. The practical effect is that - `JSDocTypeNamed_parameter` -> `JSDocTypeNamedParameter`, - `JSDocTypeRecord_entry` -> `JSDocTypeRecordEntry` - `JSDocTypeNot_nullable` -> `JSDocTypeNotNullable` - `JSDocTypeInner_member` -> `JSDocTypeInnerMember` - `JSDocTypeInstance_member` -> `JSDocTypeInstanceMember` - `JSDocTypeString_value` -> `JSDocTypeStringValue` - `JSDocTypeNumber_value` -> `JSDocTypeNumberValue` - `JSDocTypeFile_path` -> `JSDocTypeFilePath` - `JSDocTypeType_query` -> `JSDocTypeTypeQuery` - `JSDocTypeKey_query` -> `JSDocTypeKeyQuery` -- Fix: Add missing `JSDocTypeLine` to visitor keys -- Docs: Explain AST structure/differences - -## 0.4.1 - -- Docs: Indicate available methods with brief summary on README - -## 0.4.0 - -- Enhancement: Expose `parseComment` and `getTokenizers`. - -## 0.3.0 - -- Enhancement: Expose `toCamelCase` as new method rather than within a - utility file. - -## 0.2.0 - -- Enhancement: Exposes new methods: `commentHandler`, - `commentParserToESTree`, `jsdocVisitorKeys`, `jsdoctypeparserToESTree`, - `jsdocTypeVisitorKeys`, - -## 0.1.1 - -- Build: Add Babel to work with earlier Node - -## 0.1.0 - -- Initial version diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/README.md b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/README.md deleted file mode 100644 index 40d65d66d138f6..00000000000000 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/README.md +++ /dev/null @@ -1,191 +0,0 @@ -# @es-joy/jsdoccomment - -[![Node.js CI status](https://github.com/brettz9/getJSDocComment/workflows/Node.js%20CI/badge.svg)](https://github.com/brettz9/getJSDocComment/actions) - -This project aims to preserve and expand upon the -`SourceCode#getJSDocComment` functionality of the deprecated ESLint method. - -It also exports a number of functions currently for working with JSDoc: - -## 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 -- `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 `jsdoc-type-pratt-parser`. -- `getTokenizers` - A utility. Might be removed in future. -- `toCamelCase` - A utility. Might be removed in future. -- `hasSeeWithLink` - A utility to detect if a tag is `@see` and has a `@link` -- `defaultNoTypes` = The tags which allow no types by default: - `default`, `defaultvalue`, `see`; -- `defaultNoNames` - The tags which allow no names by default: - `access`, `author`, `default`, `defaultvalue`, `description`, `example`, - `exception`, `kind`, `license`, `return`, `returns`, `since`, `summary`, - `throws`, `version`, `variation` - -## ESLint AST produced for `comment-parser` nodes (`JsdocBlock`, `JsdocTag`, and `JsdocDescriptionLine`) - -Note: Although not added in this package, `@es-joy/jsdoc-eslint-parser` adds -a `jsdoc` property to other ES nodes (using this project's `getJSDocComment` -to determine the specific comment-block that will be attached as AST). - -### `JsdocBlock` - -Has two visitable properties: - -1. `tags` (an array of `JsdocTag`; see below) -2. `descriptionLines` (an array of `JsdocDescriptionLine` for multiline - descriptions). - -Has the following custom non-visitable property: - -1. `lastDescriptionLine` - A number -2. `endLine` - A number representing the line number with `end` - -May also have the following non-visitable properties from `comment-parser`: - -1. `description` - Same as `descriptionLines` but as a string with newlines. -2. `delimiter` -3. `postDelimiter` -4. `lineEnd` -5. `end` - -### `JsdocTag` - -Has three visitable properties: - -1. `parsedType` (the `jsdoc-type-pratt-parser` AST representation 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) - -May also have the following non-visitable properties from `comment-parser` -(note that all are included from `comment-parser` except `end` as that is only -for JSDoc blocks and note that `type` is renamed to `rawType`): - -1. `description` - Same as `descriptionLines` but as a string with newlines. -2. `rawType` - `comment-parser` has this named as `type`, but because of a - conflict with ESTree using `type` for Node type, we renamed it to - `rawType`. It is otherwise the same as in `comment-parser`, i.e., a string - with newlines, though with the initial `{` and final `}` stripped out. - See `typeLines` for the array version of this property. -3. `start` -4. `delimiter` -5. `postDelimiter` -6. `tag` (this does differ from `comment-parser` now in terms of our stripping - the initial `@`) -7. `postTag` -8. `name` -9. `postName` -10. `postType` - -### `JsdocDescriptionLine` - -No visitable properties. - -May also have the following non-visitable properties from `comment-parser`: - -1. `delimiter` -2. `postDelimiter` -3. `start` -4. `description` - -### `JsdocTypeLine` - -No visitable properties. - -May also have the following non-visitable properties from `comment-parser`: - -1. `delimiter` -2. `postDelimiter` -3. `start` -4. `rawType` - Renamed from `comment-parser` to avoid a conflict. See - explanation under `JsdocTag` - -## ESLint AST produced for `jsdoc-type-pratt-parser` - -The AST, including `type`, remains as is from [jsdoc-type-pratt-parser](https://github.com/simonseyock/jsdoc-type-pratt-parser/). - -The type will always begin with a `JsdocType` prefix added, along with a -camel-cased type name, e.g., `JsdocTypeUnion`. - -The `jsdoc-type-pratt-parser` visitor keys are also preserved without change. - -## Installation - -```shell -npm i @es-joy/jsdoccomment -``` - -## Changelog - -The changelog can be found on the [CHANGES.md](./CHANGES.md). - -## Authors and license - -[Brett Zamir](http://brett-zamir.me/) and -[contributors](https://github.com/es-joy/jsdoc-eslint-parser/graphs/contributors). - -MIT License, see the included [LICENSE-MIT.txt](LICENSE-MIT.txt) file. - -## To-dos - -1. Get complete code coverage diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/dist/index.cjs.cjs b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/dist/index.cjs.cjs index 38d08a8f8f470f..9926edc5828ad6 100644 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/dist/index.cjs.cjs +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/dist/index.cjs.cjs @@ -41,7 +41,7 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * postDelimiter: string, * rawType: string, - * start: string, + * initial: string, * type: "JsdocTypeLine" * }} JsdocTypeLine */ @@ -51,7 +51,7 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * postDelimiter: string, - * start: string, + * initial: string, * type: "JsdocDescriptionLine" * }} JsdocDescriptionLine */ @@ -61,9 +61,9 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * postDelimiter: string, - * start: string, + * initial: string, * tag: string, - * end: string, + * terminal: string, * type: string, * descriptionLines: JsdocDescriptionLine[], * rawType: string, @@ -77,7 +77,8 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * descriptionLines: JsdocDescriptionLine[], - * end: string, + * initial: string, + * terminal: string, * postDelimiter: string, * lineEnd: string, * type: "JsdocBlock", @@ -137,6 +138,7 @@ const commentParserToESTree = (jsdoc, mode, { delimiter: delimiterRoot, lineEnd: lineEndRoot, postDelimiter: postDelimiterRoot, + start: startRoot, end: endRoot, description: descriptionRoot } @@ -146,8 +148,9 @@ const commentParserToESTree = (jsdoc, mode, { delimiter: delimiterRoot, description: descriptionRoot, descriptionLines: [], - // `end` will be overwritten if there are other entries - end: endRoot, + initial: startRoot, + // `terminal` will be overwritten if there are other entries + terminal: endRoot, endLine, postDelimiter: postDelimiterRoot, lineEnd: lineEndRoot, @@ -164,7 +167,7 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, description, postDelimiter, - start, + start: initial, tag, end, type: rawType @@ -184,7 +187,7 @@ const commentParserToESTree = (jsdoc, mode, { if (end && !tag) { - ast.end = end; + ast.terminal = end; return; } @@ -192,21 +195,29 @@ const commentParserToESTree = (jsdoc, mode, { end: ed, delimiter: de, postDelimiter: pd, + start: init, ...tkns } = tokens; if (!tokens.name) { - let i = 0; + let i = 1; while (source[idx + i]) { const { tokens: { name, - postName + postName, + postType, + tag: tg } } = source[idx + i]; + if (tg) { + break; + } + if (name) { + tkns.postType = postType; tkns.name = name; tkns.postName = postName; break; @@ -217,6 +228,7 @@ const commentParserToESTree = (jsdoc, mode, { } const tagObj = { ...tkns, + initial: endLine ? init : '', postDelimiter: lastDescriptionLine ? pd : '', delimiter: lastDescriptionLine ? de : '', descriptionLines: [], @@ -235,13 +247,13 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, postDelimiter, rawType, - start, + initial, type: 'JsdocTypeLine' } : { delimiter: '', postDelimiter: '', rawType, - start: '', + initial: '', type: 'JsdocTypeLine' }); lastTag.rawType += lastTag.rawType ? '\n' + rawType : rawType; @@ -253,13 +265,19 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, description, postDelimiter, - start, + initial, type: 'JsdocDescriptionLine' - } : { + } : lastTag ? { delimiter: '', description, postDelimiter: '', - start: '', + initial: '', + type: 'JsdocDescriptionLine' + } : { + delimiter, + description, + postDelimiter, + initial, type: 'JsdocDescriptionLine' }); holder.description += holder.description ? '\n' + description : description; @@ -267,7 +285,7 @@ const commentParserToESTree = (jsdoc, mode, { if (end && tag) { - ast.end = end; + ast.terminal = end; cleanUpLastTag(lastTag); } }); @@ -335,6 +353,9 @@ const hasSeeWithLink = spec => { }; const defaultNoTypes = ['default', 'defaultvalue', 'see']; const defaultNoNames = ['access', 'author', 'default', 'defaultvalue', 'description', 'example', 'exception', 'kind', 'license', 'return', 'returns', 'since', 'summary', 'throws', 'version', 'variation']; +const preserveTypeTokenizer = typeTokenizer('preserve'); +const preserveDescriptionTokenizer = descriptionTokenizer('preserve'); +const plainNameTokenizer = nameTokenizer(); const getTokenizers = ({ noTypes = defaultNoTypes, @@ -348,7 +369,7 @@ const getTokenizers = ({ return spec; } - return typeTokenizer()(spec); + return preserveTypeTokenizer(spec); }, // Name spec => { if (spec.tag === 'template') { @@ -381,10 +402,10 @@ const getTokenizers = ({ return spec; } - return nameTokenizer()(spec); + return plainNameTokenizer(spec); }, // Description spec => { - return descriptionTokenizer('preserve')(spec); + return preserveDescriptionTokenizer(spec); }]; }; /** @@ -397,7 +418,7 @@ const getTokenizers = ({ const parseComment = (commentNode, indent = '') => { // Preserve JSDoc block start/end indentation. - return commentParser.parse(`/*${commentNode.value}*/`, { + return commentParser.parse(`${indent}/*${commentNode.value}*/`, { // @see https://github.com/yavorskiy/comment-parser/issues/21 tokenizers: getTokenizers() })[0]; @@ -557,6 +578,22 @@ const getReducedASTNode = function (node, sourceCode) { case 'TSEmptyBodyFunctionExpression': case 'FunctionExpression': if (!invokedExpression.has(parent.type)) { + let token = node; + + do { + token = sourceCode.getTokenBefore(token, { + includeComments: true + }); + } while (token && token.type === 'Punctuator' && token.value === '('); + + if (token && token.type === 'Block') { + return node; + } + + if (sourceCode.getCommentsBefore(node).length) { + return node; + } + while (!sourceCode.getCommentsBefore(parent).length && !/Function/u.test(parent.type) && !allowableCommentNode.has(parent.type)) { ({ parent @@ -660,53 +697,56 @@ const stringifiers = { delimiter, postDelimiter, lineEnd, - end, + initial, + terminal, endLine - }, descriptionLines, tags) { - return `${delimiter}${postDelimiter}${endLine ? ` + }, opts, descriptionLines, tags) { + const alreadyHasLine = descriptionLines.length && !tags.length && descriptionLines[descriptionLines.length - 1].endsWith('\n') || tags.length && tags[tags.length - 1].endsWith('\n'); + return `${initial}${delimiter}${postDelimiter}${endLine ? ` ` : ''}${// Could use `node.description` (and `node.lineEnd`), but lines may have // been modified - descriptionLines.length ? descriptionLines.join('') + lineEnd : ''}${tags.length ? tags.join('\n') + lineEnd : ''}${endLine ? ` - ` : ''}${end}`; + descriptionLines.length ? descriptionLines.join(lineEnd + '\n') + (tags.length ? lineEnd + '\n' : '') : ''}${tags.length ? tags.join(lineEnd + '\n') : ''}${endLine && !alreadyHasLine ? `${lineEnd} + ${initial}` : endLine ? ` ${initial}` : ''}${terminal}`; }, JsdocDescriptionLine({ - start, + initial, delimiter, postDelimiter, description }) { - return `${start}${delimiter}${postDelimiter}${description}`; + return `${initial}${delimiter}${postDelimiter}${description}`; }, JsdocTypeLine({ - start, + initial, delimiter, postDelimiter, - rawType + rawType, + parsedType }) { - return `${delimiter}${postDelimiter}{${rawType}}`; + return `${initial}${delimiter}${postDelimiter}${rawType}`; }, - JsdocTag(node, parsedType, typeLines, descriptionLines) { + JsdocTag(node, opts, parsedType, typeLines, descriptionLines) { const { description, name, postName, postTag, postType, - start, + initial, delimiter, postDelimiter, tag // , rawType } = node; - return `${start}${delimiter}${postDelimiter}@${tag}${postTag}${// Could do `rawType` but may have been changed; could also do + return `${initial}${delimiter}${postDelimiter}@${tag}${postTag}${// Could do `rawType` but may have been changed; could also do // `typeLines` but not as likely to be changed // parsedType // Comment this out later in favor of `parsedType` // We can't use raw `typeLines` as first argument has delimiter on it - typeLines}${postType}${name ? `${name}${postName || (description ? '\n' : '')}` : ''}${descriptionLines.join('\n')}`; + opts.preferRawType || !parsedType ? typeLines.length ? `{${typeLines.join('\n')}}` : '' : parsedType}${postType}${name ? `${name}${postName || (description ? '\n' : '')}` : ''}${descriptionLines.join('\n')}`; } }; @@ -717,24 +757,25 @@ const visitorKeys = { ...jsdocVisitorKeys, * @todo convert for use by escodegen (until may be patched to support * custom entries?). * @param {Node} node + * @param {{preferRawType: boolean}} opts * @throws {Error} * @returns {string} */ -function estreeToString(node) { +function estreeToString(node, opts = {}) { if (Object.prototype.hasOwnProperty.call(stringifiers, node.type)) { const childNodeOrArray = visitorKeys[node.type]; const args = childNodeOrArray.map(key => { return Array.isArray(node[key]) ? node[key].map(item => { - return estreeToString(item); - }) : node[key] === undefined || node[key] === null ? [] : [estreeToString(node[key])]; + return estreeToString(item, opts); + }) : node[key] === undefined || node[key] === null ? null : estreeToString(node[key], opts); }); - return stringifiers[node.type](node, ...args); + return stringifiers[node.type](node, opts, ...args); } // We use raw type instead but it is a key as other apps may wish to traverse if (node.type.startsWith('JsdocType')) { - return ''; + return opts.preferRawType ? '' : `{${jsdocTypePrattParser.stringify(node)}}`; } throw new Error(`Unhandled node type: ${node.type}`); diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/package.json b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/package.json index 88861cf3233815..43bf94b42df2a7 100644 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/package.json +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/package.json @@ -1,6 +1,6 @@ { "name": "@es-joy/jsdoccomment", - "version": "0.22.1", + "version": "0.29.0", "author": "Brett Zamir ", "contributors": [], "description": "Maintained replacement for ESLint's deprecated SourceCode#getJSDocComment along with other jsdoc utilities", @@ -38,41 +38,41 @@ }, "homepage": "https://github.com/es-joy/jsdoccomment", "engines": { - "node": "^12 || ^14 || ^16 || ^17" + "node": "^14 || ^16 || ^17 || ^18" }, "dependencies": { "comment-parser": "1.3.1", "esquery": "^1.4.0", - "jsdoc-type-pratt-parser": "~2.2.5" + "jsdoc-type-pratt-parser": "~3.0.1" }, "devDependencies": { - "@babel/core": "^7.17.8", + "@babel/core": "^7.17.9", "@babel/plugin-syntax-class-properties": "^7.12.13", "@babel/preset-env": "^7.16.11", "@brettz9/eslint-plugin": "^1.0.4", "@rollup/plugin-babel": "^5.3.1", - "c8": "^7.11.0", + "c8": "^7.11.2", "chai": "^4.3.6", - "eslint": "^8.11.0", - "eslint-config-ash-nazg": "32.7.1", - "eslint-config-standard": "^16.0.3", + "eslint": "^8.14.0", + "eslint-config-ash-nazg": "33.1.0", + "eslint-config-standard": "^17.0.0", "eslint-plugin-array-func": "^3.1.7", "eslint-plugin-compat": "^4.0.2", "eslint-plugin-eslint-comments": "^3.2.0", "eslint-plugin-html": "^6.2.0", - "eslint-plugin-import": "^2.25.4", - "eslint-plugin-jsdoc": "^38.0.4", + "eslint-plugin-import": "^2.26.0", + "eslint-plugin-jsdoc": "^39.2.7", "eslint-plugin-markdown": "^2.2.1", + "eslint-plugin-n": "^15.1.0", "eslint-plugin-no-unsanitized": "^4.0.1", "eslint-plugin-no-use-extend-native": "^0.5.0", - "eslint-plugin-node": "^11.1.0", "eslint-plugin-promise": "^6.0.0", - "eslint-plugin-sonarjs": "^0.12.0", - "eslint-plugin-unicorn": "^41.0.1", + "eslint-plugin-sonarjs": "^0.13.0", + "eslint-plugin-unicorn": "^42.0.0", "espree": "^9.3.1", "estraverse": "^5.3.0", "mocha": "^9.2.2", - "rollup": "^2.70.1" + "rollup": "^2.70.2" }, "scripts": { "open": "open ./coverage/lcov-report/index.html", @@ -83,5 +83,5 @@ "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`, `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\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### `estreeToString`\n\nStringifies. In addition to the node argument, it accepts an optional second\noptions object with a single `preferRawType` key. If you don't need to modify\nJSDoc type AST, you might wish to set this to `true` to get the benefits of\npreserving the raw form, but for AST-based stringification of JSDoc types,\nkeep it `false` (the default).\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`/`terminal`\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. `initial` (from `start`)\n6. `terminal` (from `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` and `start` to\n`initial`):\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. `initial` - Renamed from `start` to avoid potential conflicts with\n Acorn-style parser processing tools\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. `initial` (from `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. `initial` (from `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\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\n2. Might add `trailing` for `JsdocBlock` to know whether it is followed by a\n line break or what not; `comment-parser` does not provide, however\n3. Fix and properly utilize `indent` argument (challenging for\n `eslint-plugin-jsdoc` but needed for `jsdoc-eslint-parser` stringifiers\n to be more faithful); should also then use the proposed `trailing` as well\n" } \ No newline at end of file diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/commentParserToESTree.js b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/commentParserToESTree.js index 09e1c406711ff3..43587807406b49 100644 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/commentParserToESTree.js +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/commentParserToESTree.js @@ -36,7 +36,7 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * postDelimiter: string, * rawType: string, - * start: string, + * initial: string, * type: "JsdocTypeLine" * }} JsdocTypeLine */ @@ -46,7 +46,7 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * postDelimiter: string, - * start: string, + * initial: string, * type: "JsdocDescriptionLine" * }} JsdocDescriptionLine */ @@ -56,9 +56,9 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * postDelimiter: string, - * start: string, + * initial: string, * tag: string, - * end: string, + * terminal: string, * type: string, * descriptionLines: JsdocDescriptionLine[], * rawType: string, @@ -72,7 +72,8 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * descriptionLines: JsdocDescriptionLine[], - * end: string, + * initial: string, + * terminal: string, * postDelimiter: string, * lineEnd: string, * type: "JsdocBlock", @@ -128,6 +129,7 @@ const commentParserToESTree = (jsdoc, mode, { delimiter: delimiterRoot, lineEnd: lineEndRoot, postDelimiter: postDelimiterRoot, + start: startRoot, end: endRoot, description: descriptionRoot }} = source[0]; @@ -139,8 +141,9 @@ const commentParserToESTree = (jsdoc, mode, { descriptionLines: [], - // `end` will be overwritten if there are other entries - end: endRoot, + initial: startRoot, + // `terminal` will be overwritten if there are other entries + terminal: endRoot, endLine, postDelimiter: postDelimiterRoot, lineEnd: lineEndRoot, @@ -158,7 +161,7 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, description, postDelimiter, - start, + start: initial, tag, end, type: rawType @@ -178,7 +181,7 @@ const commentParserToESTree = (jsdoc, mode, { // but only when there is no tag earlier in the line // to still process if (end && !tag) { - ast.end = end; + ast.terminal = end; return; } @@ -187,17 +190,24 @@ const commentParserToESTree = (jsdoc, mode, { end: ed, delimiter: de, postDelimiter: pd, + start: init, ...tkns } = tokens; if (!tokens.name) { - let i = 0; + let i = 1; while (source[idx + i]) { const {tokens: { name, - postName + postName, + postType, + tag: tg }} = source[idx + i]; + if (tg) { + break; + } if (name) { + tkns.postType = postType; tkns.name = name; tkns.postName = postName; break; @@ -208,6 +218,7 @@ const commentParserToESTree = (jsdoc, mode, { const tagObj = { ...tkns, + initial: endLine ? init : '', postDelimiter: lastDescriptionLine ? pd : '', delimiter: lastDescriptionLine ? de : '', descriptionLines: [], @@ -230,14 +241,14 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, postDelimiter, rawType, - start, + initial, type: 'JsdocTypeLine' } : { delimiter: '', postDelimiter: '', rawType, - start: '', + initial: '', type: 'JsdocTypeLine' } ); @@ -252,16 +263,24 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, description, postDelimiter, - start, - type: 'JsdocDescriptionLine' - } - : { - delimiter: '', - description, - postDelimiter: '', - start: '', + initial, type: 'JsdocDescriptionLine' } + : lastTag + ? { + delimiter: '', + description, + postDelimiter: '', + initial: '', + type: 'JsdocDescriptionLine' + } + : { + delimiter, + description, + postDelimiter, + initial, + type: 'JsdocDescriptionLine' + } ); holder.description += holder.description ? '\n' + description @@ -270,7 +289,7 @@ const commentParserToESTree = (jsdoc, mode, { // Clean-up where last line itself has tag content if (end && tag) { - ast.end = end; + ast.terminal = end; cleanUpLastTag(lastTag); } diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/estreeToString.js b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/estreeToString.js index a0217f69507d61..a2fe703e53265f 100644 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/estreeToString.js +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/estreeToString.js @@ -1,52 +1,63 @@ import { - visitorKeys as jsdocTypePrattParserVisitorKeys + visitorKeys as jsdocTypePrattParserVisitorKeys, + stringify } from 'jsdoc-type-pratt-parser'; import {jsdocVisitorKeys} from './commentParserToESTree.js'; const stringifiers = { JsdocBlock ({ - delimiter, postDelimiter, lineEnd, end, endLine - }, descriptionLines, tags) { - return `${delimiter}${postDelimiter}${endLine + delimiter, postDelimiter, lineEnd, initial, terminal, endLine + }, opts, descriptionLines, tags) { + const alreadyHasLine = + (descriptionLines.length && !tags.length && + descriptionLines[descriptionLines.length - 1].endsWith('\n')) || + (tags.length && tags[tags.length - 1].endsWith('\n')); + return `${initial}${delimiter}${postDelimiter}${endLine ? ` ` : ''}${ // Could use `node.description` (and `node.lineEnd`), but lines may have // been modified - descriptionLines.length ? descriptionLines.join('') + lineEnd : '' + descriptionLines.length + ? descriptionLines.join( + lineEnd + '\n' + ) + (tags.length ? lineEnd + '\n' : '') + : '' }${ - tags.length ? tags.join('\n') + lineEnd : '' - }${endLine - ? ` - ` - : ''}${end}`; + tags.length ? tags.join(lineEnd + '\n') : '' + }${endLine && !alreadyHasLine + ? `${lineEnd} + ${initial}` + : endLine ? ` ${initial}` : ''}${terminal}`; }, JsdocDescriptionLine ({ - start, delimiter, postDelimiter, description + initial, delimiter, postDelimiter, description }) { - return `${start}${delimiter}${postDelimiter}${description}`; + return `${initial}${delimiter}${postDelimiter}${description}`; }, JsdocTypeLine ({ - start, delimiter, postDelimiter, rawType + initial, delimiter, postDelimiter, rawType, parsedType }) { - return `${delimiter}${postDelimiter}{${rawType}}`; + return `${initial}${delimiter}${postDelimiter}${rawType}`; }, - JsdocTag (node, parsedType, typeLines, descriptionLines) { + JsdocTag (node, opts, parsedType, typeLines, descriptionLines) { const { description, name, postName, postTag, postType, - start, delimiter, postDelimiter, tag + initial, delimiter, postDelimiter, tag // , rawType } = node; - return `${start}${delimiter}${postDelimiter}@${tag}${postTag}${ + return `${initial}${delimiter}${postDelimiter}@${tag}${postTag}${ // Could do `rawType` but may have been changed; could also do // `typeLines` but not as likely to be changed // parsedType // Comment this out later in favor of `parsedType` // We can't use raw `typeLines` as first argument has delimiter on it - typeLines + (opts.preferRawType || !parsedType) + ? typeLines.length ? `{${typeLines.join('\n')}}` : '' + : parsedType }${postType}${ name ? `${name}${postName || (description ? '\n' : '')}` : '' }${descriptionLines.join('\n')}`; @@ -59,29 +70,29 @@ const visitorKeys = {...jsdocVisitorKeys, ...jsdocTypePrattParserVisitorKeys}; * @todo convert for use by escodegen (until may be patched to support * custom entries?). * @param {Node} node + * @param {{preferRawType: boolean}} opts * @throws {Error} * @returns {string} */ -function estreeToString (node) { +function estreeToString (node, opts = {}) { if (Object.prototype.hasOwnProperty.call(stringifiers, node.type)) { const childNodeOrArray = visitorKeys[node.type]; const args = childNodeOrArray.map((key) => { return Array.isArray(node[key]) ? node[key].map((item) => { - return estreeToString(item); + return estreeToString(item, opts); }) : (node[key] === undefined || node[key] === null - ? [] - : [estreeToString(node[key])]); + ? null + : estreeToString(node[key], opts)); }); - - return stringifiers[node.type](node, ...args); + return stringifiers[node.type](node, opts, ...args); } // We use raw type instead but it is a key as other apps may wish to traverse if (node.type.startsWith('JsdocType')) { - return ''; + return opts.preferRawType ? '' : `{${stringify(node)}}`; } throw new Error(`Unhandled node type: ${node.type}`); diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/jsdoccomment.js b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/jsdoccomment.js index 295b3a807afb10..7a20d23ca437f4 100644 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/jsdoccomment.js +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/jsdoccomment.js @@ -160,6 +160,18 @@ const getReducedASTNode = function (node, sourceCode) { if ( !invokedExpression.has(parent.type) ) { + let token = node; + do { + token = sourceCode.getTokenBefore(token, {includeComments: true}); + } while (token && token.type === 'Punctuator' && token.value === '('); + + if (token && token.type === 'Block') { + return node; + } + + if (sourceCode.getCommentsBefore(node).length) { + return node; + } while ( !sourceCode.getCommentsBefore(parent).length && !(/Function/u).test(parent.type) && diff --git a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/parseComment.js b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/parseComment.js index bd8df053dd0ef2..44942678acd253 100644 --- a/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/parseComment.js +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/src/parseComment.js @@ -29,6 +29,10 @@ export const defaultNoNames = [ 'version', 'variation' ]; +const preserveTypeTokenizer = typeTokenizer('preserve'); +const preserveDescriptionTokenizer = descriptionTokenizer('preserve'); +const plainNameTokenizer = nameTokenizer(); + const getTokenizers = ({ noTypes = defaultNoTypes, noNames = defaultNoNames @@ -44,7 +48,7 @@ const getTokenizers = ({ return spec; } - return typeTokenizer()(spec); + return preserveTypeTokenizer(spec); }, // Name @@ -77,12 +81,12 @@ const getTokenizers = ({ return spec; } - return nameTokenizer()(spec); + return plainNameTokenizer(spec); }, // Description (spec) => { - return descriptionTokenizer('preserve')(spec); + return preserveDescriptionTokenizer(spec); } ]; }; @@ -95,7 +99,7 @@ const getTokenizers = ({ */ const parseComment = (commentNode, indent = '') => { // Preserve JSDoc block start/end indentation. - return commentParser(`/*${commentNode.value}*/`, { + return commentParser(`${indent}/*${commentNode.value}*/`, { // @see https://github.com/yavorskiy/comment-parser/issues/21 tokenizers: getTokenizers() })[0]; diff --git a/tools/node_modules/eslint/node_modules/browserslist/index.js b/tools/node_modules/eslint/node_modules/browserslist/index.js index 8c09141c696faa..37e35b30d56c25 100644 --- a/tools/node_modules/eslint/node_modules/browserslist/index.js +++ b/tools/node_modules/eslint/node_modules/browserslist/index.js @@ -1175,6 +1175,7 @@ var QUERIES = [ regexp: /^dead$/i, select: function (context) { var dead = [ + 'Baidu >= 0', 'ie <= 10', 'ie_mob <= 11', 'bb <= 10', diff --git a/tools/node_modules/eslint/node_modules/browserslist/package.json b/tools/node_modules/eslint/node_modules/browserslist/package.json index 483db2c28bd6a0..1c5acf3d5fda58 100644 --- a/tools/node_modules/eslint/node_modules/browserslist/package.json +++ b/tools/node_modules/eslint/node_modules/browserslist/package.json @@ -1,6 +1,6 @@ { "name": "browserslist", - "version": "4.20.2", + "version": "4.20.3", "description": "Share target browsers between different front-end tools, like Autoprefixer, Stylelint and babel-env-preset", "keywords": [ "caniuse", @@ -21,10 +21,10 @@ "license": "MIT", "repository": "browserslist/browserslist", "dependencies": { - "caniuse-lite": "^1.0.30001317", - "electron-to-chromium": "^1.4.84", + "caniuse-lite": "^1.0.30001332", + "electron-to-chromium": "^1.4.118", "escalade": "^3.1.1", - "node-releases": "^2.0.2", + "node-releases": "^2.0.3", "picocolors": "^1.0.0" }, "engines": { diff --git a/tools/node_modules/eslint/node_modules/eslint-plugin-jsdoc/package.json b/tools/node_modules/eslint/node_modules/eslint-plugin-jsdoc/package.json index 03a0ef3730477a..e3c64e36d567d3 100644 --- a/tools/node_modules/eslint/node_modules/eslint-plugin-jsdoc/package.json +++ b/tools/node_modules/eslint/node_modules/eslint-plugin-jsdoc/package.json @@ -5,7 +5,7 @@ "url": "http://gajus.com" }, "dependencies": { - "@es-joy/jsdoccomment": "~0.28.0", + "@es-joy/jsdoccomment": "~0.29.0", "comment-parser": "1.3.1", "debug": "^4.3.4", "escape-string-regexp": "^4.0.0", @@ -32,13 +32,13 @@ "chai": "^4.3.6", "cross-env": "^7.0.3", "decamelize": "^5.0.1", - "eslint": "^8.13.0", + "eslint": "^8.14.0", "eslint-config-canonical": "~33.0.1", "gitdown": "^3.1.5", "glob": "^8.0.1", "husky": "^7.0.4", "jsdoc-type-pratt-parser": "^3.0.1", - "lint-staged": "^12.3.8", + "lint-staged": "^12.4.0", "lodash.defaultsdeep": "^4.6.1", "mocha": "^9.2.2", "nyc": "^15.1.0", @@ -117,5 +117,5 @@ "test-cov": "cross-env TIMING=1 nyc --reporter text npm run test-no-cov", "test-index": "npm run test-no-cov -- test/rules/index.js" }, - "version": "39.2.7" + "version": "39.2.8" }