From a09748ea8564d4209cd612c8ba5143585f2cc2b8 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 23 Apr 2022 22:48:07 -0700 Subject: [PATCH] fixup! tools: update eslint to 8.14.0 --- .../@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 | 24 +- .../jsdoccomment/src/commentParserToESTree.js | 63 ++-- .../jsdoccomment/src/estreeToString.js | 61 ++- .../@es-joy/jsdoccomment/src/jsdoccomment.js | 12 - .../@es-joy/jsdoccomment/src/parseComment.js | 12 +- 11 files changed, 699 insertions(+), 190 deletions(-) create mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.editorconfig create mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintignore create mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintrc.cjs create mode 100644 tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/CHANGES.md create 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 new file mode 100644 index 00000000000000..ff45b8651f9a06 --- /dev/null +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.editorconfig @@ -0,0 +1,15 @@ +; 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 new file mode 100644 index 00000000000000..132e9461546f2a --- /dev/null +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintignore @@ -0,0 +1,4 @@ +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 new file mode 100644 index 00000000000000..ce02e48c878103 --- /dev/null +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/.eslintrc.cjs @@ -0,0 +1,31 @@ +'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 new file mode 100644 index 00000000000000..ae33b447ec6a48 --- /dev/null +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/CHANGES.md @@ -0,0 +1,355 @@ +# 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 new file mode 100644 index 00000000000000..40d65d66d138f6 --- /dev/null +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/README.md @@ -0,0 +1,191 @@ +# @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 b8772ae3f24a4a..38d08a8f8f470f 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, - * initial: string, + * start: string, * type: "JsdocTypeLine" * }} JsdocTypeLine */ @@ -51,7 +51,7 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * postDelimiter: string, - * initial: string, + * start: string, * type: "JsdocDescriptionLine" * }} JsdocDescriptionLine */ @@ -61,9 +61,9 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * postDelimiter: string, - * initial: string, + * start: string, * tag: string, - * terminal: string, + * end: string, * type: string, * descriptionLines: JsdocDescriptionLine[], * rawType: string, @@ -77,8 +77,7 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * descriptionLines: JsdocDescriptionLine[], - * initial: string, - * terminal: string, + * end: string, * postDelimiter: string, * lineEnd: string, * type: "JsdocBlock", @@ -138,7 +137,6 @@ const commentParserToESTree = (jsdoc, mode, { delimiter: delimiterRoot, lineEnd: lineEndRoot, postDelimiter: postDelimiterRoot, - start: startRoot, end: endRoot, description: descriptionRoot } @@ -148,9 +146,8 @@ const commentParserToESTree = (jsdoc, mode, { delimiter: delimiterRoot, description: descriptionRoot, descriptionLines: [], - initial: startRoot, - // `terminal` will be overwritten if there are other entries - terminal: endRoot, + // `end` will be overwritten if there are other entries + end: endRoot, endLine, postDelimiter: postDelimiterRoot, lineEnd: lineEndRoot, @@ -167,7 +164,7 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, description, postDelimiter, - start: initial, + start, tag, end, type: rawType @@ -187,7 +184,7 @@ const commentParserToESTree = (jsdoc, mode, { if (end && !tag) { - ast.terminal = end; + ast.end = end; return; } @@ -195,29 +192,21 @@ const commentParserToESTree = (jsdoc, mode, { end: ed, delimiter: de, postDelimiter: pd, - start: init, ...tkns } = tokens; if (!tokens.name) { - let i = 1; + let i = 0; while (source[idx + i]) { const { tokens: { name, - postName, - postType, - tag: tg + postName } } = source[idx + i]; - if (tg) { - break; - } - if (name) { - tkns.postType = postType; tkns.name = name; tkns.postName = postName; break; @@ -228,7 +217,6 @@ const commentParserToESTree = (jsdoc, mode, { } const tagObj = { ...tkns, - initial: endLine ? init : '', postDelimiter: lastDescriptionLine ? pd : '', delimiter: lastDescriptionLine ? de : '', descriptionLines: [], @@ -247,13 +235,13 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, postDelimiter, rawType, - initial, + start, type: 'JsdocTypeLine' } : { delimiter: '', postDelimiter: '', rawType, - initial: '', + start: '', type: 'JsdocTypeLine' }); lastTag.rawType += lastTag.rawType ? '\n' + rawType : rawType; @@ -265,19 +253,13 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, description, postDelimiter, - initial, + start, type: 'JsdocDescriptionLine' - } : lastTag ? { + } : { delimiter: '', description, postDelimiter: '', - initial: '', - type: 'JsdocDescriptionLine' - } : { - delimiter, - description, - postDelimiter, - initial, + start: '', type: 'JsdocDescriptionLine' }); holder.description += holder.description ? '\n' + description : description; @@ -285,7 +267,7 @@ const commentParserToESTree = (jsdoc, mode, { if (end && tag) { - ast.terminal = end; + ast.end = end; cleanUpLastTag(lastTag); } }); @@ -353,9 +335,6 @@ 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, @@ -369,7 +348,7 @@ const getTokenizers = ({ return spec; } - return preserveTypeTokenizer(spec); + return typeTokenizer()(spec); }, // Name spec => { if (spec.tag === 'template') { @@ -402,10 +381,10 @@ const getTokenizers = ({ return spec; } - return plainNameTokenizer(spec); + return nameTokenizer()(spec); }, // Description spec => { - return preserveDescriptionTokenizer(spec); + return descriptionTokenizer('preserve')(spec); }]; }; /** @@ -418,7 +397,7 @@ const getTokenizers = ({ const parseComment = (commentNode, indent = '') => { // Preserve JSDoc block start/end indentation. - return commentParser.parse(`${indent}/*${commentNode.value}*/`, { + return commentParser.parse(`/*${commentNode.value}*/`, { // @see https://github.com/yavorskiy/comment-parser/issues/21 tokenizers: getTokenizers() })[0]; @@ -578,22 +557,6 @@ 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.type === 'Punctuator' && token.value === '('); - - if (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 @@ -697,56 +660,53 @@ const stringifiers = { delimiter, postDelimiter, lineEnd, - initial, - terminal, + end, 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 ? ` + }, descriptionLines, tags) { + return `${delimiter}${postDelimiter}${endLine ? ` ` : ''}${// Could use `node.description` (and `node.lineEnd`), but lines may have // been modified - descriptionLines.length ? descriptionLines.join(lineEnd + '\n') + (tags.length ? lineEnd + '\n' : '') : ''}${tags.length ? tags.join(lineEnd + '\n') : ''}${endLine && !alreadyHasLine ? `${lineEnd} - ${initial}` : endLine ? ` ${initial}` : ''}${terminal}`; + descriptionLines.length ? descriptionLines.join('') + lineEnd : ''}${tags.length ? tags.join('\n') + lineEnd : ''}${endLine ? ` + ` : ''}${end}`; }, JsdocDescriptionLine({ - initial, + start, delimiter, postDelimiter, description }) { - return `${initial}${delimiter}${postDelimiter}${description}`; + return `${start}${delimiter}${postDelimiter}${description}`; }, JsdocTypeLine({ - initial, + start, delimiter, postDelimiter, - rawType, - parsedType + rawType }) { - return `${initial}${delimiter}${postDelimiter}${rawType}`; + return `${delimiter}${postDelimiter}{${rawType}}`; }, - JsdocTag(node, opts, parsedType, typeLines, descriptionLines) { + JsdocTag(node, parsedType, typeLines, descriptionLines) { const { description, name, postName, postTag, postType, - initial, + start, delimiter, postDelimiter, tag // , rawType } = node; - return `${initial}${delimiter}${postDelimiter}@${tag}${postTag}${// Could do `rawType` but may have been changed; could also do + return `${start}${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 - opts.preferRawType || !parsedType ? typeLines.length ? `{${typeLines.join('\n')}}` : '' : parsedType}${postType}${name ? `${name}${postName || (description ? '\n' : '')}` : ''}${descriptionLines.join('\n')}`; + typeLines}${postType}${name ? `${name}${postName || (description ? '\n' : '')}` : ''}${descriptionLines.join('\n')}`; } }; @@ -757,25 +717,24 @@ 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, opts = {}) { +function estreeToString(node) { 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, opts); - }) : node[key] === undefined || node[key] === null ? null : estreeToString(node[key], opts); + return estreeToString(item); + }) : node[key] === undefined || node[key] === null ? [] : [estreeToString(node[key])]; }); - return stringifiers[node.type](node, opts, ...args); + return stringifiers[node.type](node, ...args); } // We use raw type instead but it is a key as other apps may wish to traverse if (node.type.startsWith('JsdocType')) { - return opts.preferRawType ? '' : `{${jsdocTypePrattParser.stringify(node)}}`; + return ''; } 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 2322cdb286a6ef..88861cf3233815 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.28.0", + "version": "0.22.1", "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 || ^18" + "node": "^12 || ^14 || ^16 || ^17" }, "dependencies": { "comment-parser": "1.3.1", "esquery": "^1.4.0", - "jsdoc-type-pratt-parser": "~3.0.1" + "jsdoc-type-pratt-parser": "~2.2.5" }, "devDependencies": { - "@babel/core": "^7.17.9", + "@babel/core": "^7.17.8", "@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", "chai": "^4.3.6", - "eslint": "^8.13.0", - "eslint-config-ash-nazg": "32.14.0", + "eslint": "^8.11.0", + "eslint-config-ash-nazg": "32.7.1", "eslint-config-standard": "^16.0.3", "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.26.0", - "eslint-plugin-jsdoc": "^39.2.4", + "eslint-plugin-import": "^2.25.4", + "eslint-plugin-jsdoc": "^38.0.4", "eslint-plugin-markdown": "^2.2.1", "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.13.0", - "eslint-plugin-unicorn": "^42.0.0", + "eslint-plugin-sonarjs": "^0.12.0", + "eslint-plugin-unicorn": "^41.0.1", "espree": "^9.3.1", "estraverse": "^5.3.0", "mocha": "^9.2.2", - "rollup": "^2.70.2" + "rollup": "^2.70.1" }, "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### `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" + "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" } \ 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 43587807406b49..09e1c406711ff3 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, - * initial: string, + * start: string, * type: "JsdocTypeLine" * }} JsdocTypeLine */ @@ -46,7 +46,7 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * postDelimiter: string, - * initial: string, + * start: string, * type: "JsdocDescriptionLine" * }} JsdocDescriptionLine */ @@ -56,9 +56,9 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * postDelimiter: string, - * initial: string, + * start: string, * tag: string, - * terminal: string, + * end: string, * type: string, * descriptionLines: JsdocDescriptionLine[], * rawType: string, @@ -72,8 +72,7 @@ const stripEncapsulatingBrackets = (container, isArr) => { * delimiter: string, * description: string, * descriptionLines: JsdocDescriptionLine[], - * initial: string, - * terminal: string, + * end: string, * postDelimiter: string, * lineEnd: string, * type: "JsdocBlock", @@ -129,7 +128,6 @@ const commentParserToESTree = (jsdoc, mode, { delimiter: delimiterRoot, lineEnd: lineEndRoot, postDelimiter: postDelimiterRoot, - start: startRoot, end: endRoot, description: descriptionRoot }} = source[0]; @@ -141,9 +139,8 @@ const commentParserToESTree = (jsdoc, mode, { descriptionLines: [], - initial: startRoot, - // `terminal` will be overwritten if there are other entries - terminal: endRoot, + // `end` will be overwritten if there are other entries + end: endRoot, endLine, postDelimiter: postDelimiterRoot, lineEnd: lineEndRoot, @@ -161,7 +158,7 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, description, postDelimiter, - start: initial, + start, tag, end, type: rawType @@ -181,7 +178,7 @@ const commentParserToESTree = (jsdoc, mode, { // but only when there is no tag earlier in the line // to still process if (end && !tag) { - ast.terminal = end; + ast.end = end; return; } @@ -190,24 +187,17 @@ const commentParserToESTree = (jsdoc, mode, { end: ed, delimiter: de, postDelimiter: pd, - start: init, ...tkns } = tokens; if (!tokens.name) { - let i = 1; + let i = 0; while (source[idx + i]) { const {tokens: { name, - postName, - postType, - tag: tg + postName }} = source[idx + i]; - if (tg) { - break; - } if (name) { - tkns.postType = postType; tkns.name = name; tkns.postName = postName; break; @@ -218,7 +208,6 @@ const commentParserToESTree = (jsdoc, mode, { const tagObj = { ...tkns, - initial: endLine ? init : '', postDelimiter: lastDescriptionLine ? pd : '', delimiter: lastDescriptionLine ? de : '', descriptionLines: [], @@ -241,14 +230,14 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, postDelimiter, rawType, - initial, + start, type: 'JsdocTypeLine' } : { delimiter: '', postDelimiter: '', rawType, - initial: '', + start: '', type: 'JsdocTypeLine' } ); @@ -263,24 +252,16 @@ const commentParserToESTree = (jsdoc, mode, { delimiter, description, postDelimiter, - initial, + start, + type: 'JsdocDescriptionLine' + } + : { + delimiter: '', + description, + postDelimiter: '', + start: '', type: 'JsdocDescriptionLine' } - : lastTag - ? { - delimiter: '', - description, - postDelimiter: '', - initial: '', - type: 'JsdocDescriptionLine' - } - : { - delimiter, - description, - postDelimiter, - initial, - type: 'JsdocDescriptionLine' - } ); holder.description += holder.description ? '\n' + description @@ -289,7 +270,7 @@ const commentParserToESTree = (jsdoc, mode, { // Clean-up where last line itself has tag content if (end && tag) { - ast.terminal = end; + ast.end = 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 a2fe703e53265f..a0217f69507d61 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,63 +1,52 @@ import { - visitorKeys as jsdocTypePrattParserVisitorKeys, - stringify + visitorKeys as jsdocTypePrattParserVisitorKeys } from 'jsdoc-type-pratt-parser'; import {jsdocVisitorKeys} from './commentParserToESTree.js'; const stringifiers = { JsdocBlock ({ - 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 + delimiter, postDelimiter, lineEnd, end, endLine + }, descriptionLines, tags) { + return `${delimiter}${postDelimiter}${endLine ? ` ` : ''}${ // Could use `node.description` (and `node.lineEnd`), but lines may have // been modified - descriptionLines.length - ? descriptionLines.join( - lineEnd + '\n' - ) + (tags.length ? lineEnd + '\n' : '') - : '' + descriptionLines.length ? descriptionLines.join('') + lineEnd : '' }${ - tags.length ? tags.join(lineEnd + '\n') : '' - }${endLine && !alreadyHasLine - ? `${lineEnd} - ${initial}` - : endLine ? ` ${initial}` : ''}${terminal}`; + tags.length ? tags.join('\n') + lineEnd : '' + }${endLine + ? ` + ` + : ''}${end}`; }, JsdocDescriptionLine ({ - initial, delimiter, postDelimiter, description + start, delimiter, postDelimiter, description }) { - return `${initial}${delimiter}${postDelimiter}${description}`; + return `${start}${delimiter}${postDelimiter}${description}`; }, JsdocTypeLine ({ - initial, delimiter, postDelimiter, rawType, parsedType + start, delimiter, postDelimiter, rawType }) { - return `${initial}${delimiter}${postDelimiter}${rawType}`; + return `${delimiter}${postDelimiter}{${rawType}}`; }, - JsdocTag (node, opts, parsedType, typeLines, descriptionLines) { + JsdocTag (node, parsedType, typeLines, descriptionLines) { const { description, name, postName, postTag, postType, - initial, delimiter, postDelimiter, tag + start, delimiter, postDelimiter, tag // , rawType } = node; - return `${initial}${delimiter}${postDelimiter}@${tag}${postTag}${ + return `${start}${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 - (opts.preferRawType || !parsedType) - ? typeLines.length ? `{${typeLines.join('\n')}}` : '' - : parsedType + typeLines }${postType}${ name ? `${name}${postName || (description ? '\n' : '')}` : '' }${descriptionLines.join('\n')}`; @@ -70,29 +59,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, opts = {}) { +function estreeToString (node) { 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, opts); + return estreeToString(item); }) : (node[key] === undefined || node[key] === null - ? null - : estreeToString(node[key], opts)); + ? [] + : [estreeToString(node[key])]); }); - return stringifiers[node.type](node, opts, ...args); + + return stringifiers[node.type](node, ...args); } // We use raw type instead but it is a key as other apps may wish to traverse if (node.type.startsWith('JsdocType')) { - return opts.preferRawType ? '' : `{${stringify(node)}}`; + return ''; } 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 bf1be0a1aa9aa5..295b3a807afb10 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,18 +160,6 @@ const getReducedASTNode = function (node, sourceCode) { if ( !invokedExpression.has(parent.type) ) { - let token = node; - do { - token = sourceCode.getTokenBefore(token, {includeComments: true}); - } while (token.type === 'Punctuator' && token.value === '('); - - if (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 44942678acd253..bd8df053dd0ef2 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,10 +29,6 @@ export const defaultNoNames = [ 'version', 'variation' ]; -const preserveTypeTokenizer = typeTokenizer('preserve'); -const preserveDescriptionTokenizer = descriptionTokenizer('preserve'); -const plainNameTokenizer = nameTokenizer(); - const getTokenizers = ({ noTypes = defaultNoTypes, noNames = defaultNoNames @@ -48,7 +44,7 @@ const getTokenizers = ({ return spec; } - return preserveTypeTokenizer(spec); + return typeTokenizer()(spec); }, // Name @@ -81,12 +77,12 @@ const getTokenizers = ({ return spec; } - return plainNameTokenizer(spec); + return nameTokenizer()(spec); }, // Description (spec) => { - return preserveDescriptionTokenizer(spec); + return descriptionTokenizer('preserve')(spec); } ]; }; @@ -99,7 +95,7 @@ const getTokenizers = ({ */ const parseComment = (commentNode, indent = '') => { // Preserve JSDoc block start/end indentation. - return commentParser(`${indent}/*${commentNode.value}*/`, { + return commentParser(`/*${commentNode.value}*/`, { // @see https://github.com/yavorskiy/comment-parser/issues/21 tokenizers: getTokenizers() })[0];