diff options
Diffstat (limited to 'tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment')
5 files changed, 596 insertions, 0 deletions
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 00000000000..ff45b8651f9 --- /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 00000000000..132e9461546 --- /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 00000000000..ce02e48c878 --- /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 00000000000..ae33b447ec6 --- /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 00000000000..40d65d66d13 --- /dev/null +++ b/tools/node_modules/eslint/node_modules/@es-joy/jsdoccomment/README.md @@ -0,0 +1,191 @@ +# @es-joy/jsdoccomment + +[](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). +<!--## Contributing + +Everyone is welcome to contribute. Please take a moment to review the [contributing guidelines](CONTRIBUTING.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 |