Initial import with skill sheet working
This commit is contained in:
589
node_modules/@es-joy/jsdoccomment/CHANGES.md
generated
vendored
Normal file
589
node_modules/@es-joy/jsdoccomment/CHANGES.md
generated
vendored
Normal file
@ -0,0 +1,589 @@
|
||||
# CHANGES for `@es-joy/jsdoccomment`
|
||||
|
||||
## 0.46.0
|
||||
|
||||
- chore: update esquery, drop bundling of types, update devDeps
|
||||
|
||||
## 0.45.0
|
||||
|
||||
- feat: get following comment (experimental)
|
||||
|
||||
## 0.44.0
|
||||
|
||||
- feat: add `getNonJsdocComment` for getting non-JSDoc comments above node
|
||||
|
||||
## 0.43.1
|
||||
|
||||
- fix: for `@template` name parsing, ensure (default-)bracketed name is not broken with internal spaces.
|
||||
|
||||
## 0.43.0
|
||||
|
||||
This release brings surgical round trip parsing to generated AST and reconstruction of JSDoc comment blocks via: `parseComment` ->
|
||||
`commentParserToESTree` -> `estreeToString`.
|
||||
|
||||
- feat: new option `spacing` for `commentParserToESTree`; the default is `compact` removing empty description lines.
|
||||
Set to `preserve` to retain empty description lines.
|
||||
- feat: new properties in the `JsdocBlock` generated AST `delimiterLineBreak` and `preterminalLineBreak` that encode
|
||||
any line break after the opening `delimiter` and before the closing `terminal` string. Values are either `\n` or an
|
||||
empty string.
|
||||
|
||||
- chore: update devDeps / switch to Vitest.
|
||||
|
||||
- New [API documentation](https://es-joy.github.io/jsdoccomment/).
|
||||
|
||||
Thanks:
|
||||
- [@typhonrt](https://github.com/typhonrt)
|
||||
|
||||
## 0.42.0
|
||||
|
||||
- feat: expand argument for `parseComment` to accept a comment token string ([@typhonrt](https://github.com/typhonrt))
|
||||
- chore: update devDeps.
|
||||
|
||||
## 0.41.0
|
||||
|
||||
- feat: look above surrounding parenthesis tokens for comment blocks, even if on a higher line than the corresponding AST structure
|
||||
- chore: update comment-parser and devDeps.
|
||||
|
||||
## 0.40.1
|
||||
|
||||
- chore(TS): fix path issue
|
||||
|
||||
## 0.40.0
|
||||
|
||||
- chore: update comment-parser and devDeps.
|
||||
- chore(TS): switch to NodeNext
|
||||
|
||||
## 0.39.4
|
||||
|
||||
- fix: include type exports for full inlineTags (and line) property support on blocks and tags
|
||||
|
||||
## 0.39.3
|
||||
|
||||
- fix: add type details for Node range and settings
|
||||
|
||||
## 0.39.2
|
||||
|
||||
- fix: export additional typedefs from index.js
|
||||
|
||||
## 0.39.1
|
||||
|
||||
- fix: typing export
|
||||
|
||||
## 0.39.0
|
||||
|
||||
- feat: types for test files and emit declaration files
|
||||
- fix(estreeToString): add `JsdodInlineTag` stringify support
|
||||
- refactor: lint
|
||||
- docs: add `JsdocInlineTag` to README
|
||||
- chore: update devDeps.
|
||||
|
||||
## 0.38.0
|
||||
|
||||
- feat: add parsing inline tags (#12); fixes #11
|
||||
|
||||
## 0.37.1
|
||||
|
||||
- chore: support Node 20
|
||||
- chore: update esquery, devDeps.
|
||||
|
||||
## 0.37.0
|
||||
## 0.37.0-pre.0
|
||||
|
||||
- fix: update `jsdoc-type-pratt-parser` (supports bracket indexes)
|
||||
|
||||
## 0.36.1
|
||||
|
||||
- fix(`getReducedASTNode`): stop checking for comment blocks at return
|
||||
statement
|
||||
|
||||
## 0.36.0
|
||||
|
||||
- feat: add `hasPreterminalTagDescription` property
|
||||
- fix: avoid description line properties if tag is present
|
||||
- fix: ensure description and description lines added to terminal multi-line tag
|
||||
|
||||
## 0.35.0
|
||||
|
||||
- feat: add `hasPreterminalDescription` property
|
||||
- fix: allow newline even for 1st line (after 0th)
|
||||
|
||||
## 0.34.0
|
||||
|
||||
- feat: add `descriptionStartLine` and `descriptionEndLine` properties
|
||||
- fix: avoid duplication with 0 line comments
|
||||
- chore: update devDeps.
|
||||
|
||||
## 0.33.4
|
||||
|
||||
- chore: republish as npm seems to have missed the release
|
||||
|
||||
## 0.33.3
|
||||
|
||||
- fix: ensure multi-line `description` includes newline except for
|
||||
initial line descriptions
|
||||
|
||||
## 0.33.2
|
||||
|
||||
- fix: avoid repetition within multi-line descriptions
|
||||
|
||||
## 0.33.1
|
||||
|
||||
- fix: add to default no types: `description`, `example`, `file`,
|
||||
`fileoverview`, `license`, `overview`, `see`, `summary`
|
||||
- fix: add to no names: `file`, `fileoverview, `overview`
|
||||
|
||||
## 0.33.0
|
||||
|
||||
- chore: add Node 19 to `engines` (@RodEsp)
|
||||
- chore: update devDeps. and build file accordingly
|
||||
|
||||
## 0.32.0
|
||||
|
||||
- feat: have comment checking stop at assignment patterns (comments for
|
||||
defaults should not rise to function itself)
|
||||
- chore: bump devDeps.
|
||||
|
||||
## 0.31.0
|
||||
|
||||
- feat: support default values with `@template` per
|
||||
<https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template>
|
||||
|
||||
## 0.30.0
|
||||
|
||||
- chore: bump `jsdoc-type-pratt-parser` and devDeps.
|
||||
|
||||
## 0.29.0
|
||||
|
||||
- fix: update `engines` as per current `getJSDocComment` behavior
|
||||
- chore: update devDeps.
|
||||
|
||||
## 0.28.1
|
||||
|
||||
- fix(`getReducedASTNode`): token checking
|
||||
- build: add Node 18 support (@WikiRik)
|
||||
|
||||
## 0.28.0
|
||||
|
||||
- chore: bump `engines` to support Node 18
|
||||
|
||||
## 0.27.0
|
||||
|
||||
- chore: bump `jsdoc-type-pratt-parser` and devDeps.
|
||||
|
||||
## 0.26.1
|
||||
|
||||
- fix(`estreeToString`): ensure `typeLines` may be picked up
|
||||
|
||||
## 0.26.0
|
||||
|
||||
- feat(`getJSDocComment`): allow function to detect comments just preceding a
|
||||
parenthesized expression (these have no special AST but their tokens
|
||||
have to be overpassed)
|
||||
|
||||
## 0.25.0
|
||||
|
||||
- feat(`parseComment`): properly support whitespace
|
||||
- fix(`estreeToString`): carriage return placement for ending of JSDoc block
|
||||
- fix(`commentParserToESTree`): avoid adding initial space before a tag if on
|
||||
a single line
|
||||
- test: make tests more accurate to jsdoc semantically
|
||||
|
||||
## 0.24.0
|
||||
|
||||
- feat(`estreeToString`): support stringification of `parsedType` but with
|
||||
a new `preferRawType` option allowing the old behavior of using `rawType`
|
||||
|
||||
## 0.23.6
|
||||
|
||||
- fix(`commentParserToESTree`): ensure `postType` added after multi-line type
|
||||
- fix(`estreeToString`): ensure `JsdocTypeLine` stringified with `initial` and
|
||||
that they are joined together with newlines
|
||||
|
||||
## 0.23.5
|
||||
|
||||
- fix(`commentParserToESTree`): avoid duplicating tag names
|
||||
|
||||
## 0.23.4
|
||||
|
||||
- fix(`estreeToString`): add `delimiter`, etc. if adding `JsdocDescriptionLine`
|
||||
for `JsdocBlock`
|
||||
- fix(`estreeToString`): add line break when tags are present (unless already
|
||||
ending in newline)
|
||||
|
||||
## 0.23.3
|
||||
|
||||
- fix(`estreeToString`): handle multi-line block descriptions followed by
|
||||
tags with line break
|
||||
|
||||
## 0.23.2
|
||||
|
||||
- fix: ensure JsdocBlock stringifier has any initial whitespace on end line
|
||||
|
||||
## 0.23.1
|
||||
|
||||
- docs(README): update
|
||||
|
||||
## 0.23.0
|
||||
|
||||
- BREAKING CHANGE(`commentParserToESTree`): rename `start` and `end` to
|
||||
`initial` and `terminal` to avoid any conflicts with Acorn-style parsers
|
||||
- feat: add `initial` and `terminal` on `JsdocBlock`
|
||||
|
||||
## 0.22.2
|
||||
|
||||
- fix: preserve type tokens
|
||||
- perf: cache tokenizers
|
||||
|
||||
## 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
|
||||
20
node_modules/@es-joy/jsdoccomment/LICENSE-MIT.txt
generated
vendored
Normal file
20
node_modules/@es-joy/jsdoccomment/LICENSE-MIT.txt
generated
vendored
Normal file
@ -0,0 +1,20 @@
|
||||
Copyright JS Foundation and other contributors, https://js.foundation
|
||||
Copyright (c) 2021 Brett Zamir
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in
|
||||
all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
||||
THE SOFTWARE.
|
||||
241
node_modules/@es-joy/jsdoccomment/README.md
generated
vendored
Normal file
241
node_modules/@es-joy/jsdoccomment/README.md
generated
vendored
Normal file
@ -0,0 +1,241 @@
|
||||
# @es-joy/jsdoccomment
|
||||
|
||||
[](https://www.npmjs.com/package/@es-joy/jsdoccomment)
|
||||
[](https://github.com/es-joy/jsdoccomment/blob/main/LICENSE-MIT.txt)
|
||||
[](#)
|
||||
[](https://es-joy.github.io/jsdoccomment/)
|
||||
|
||||
|
||||
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.
|
||||
|
||||
### `estreeToString`
|
||||
|
||||
Stringifies. In addition to the node argument, it accepts an optional second
|
||||
options object with a single `preferRawType` key. If you don't need to modify
|
||||
JSDoc type AST, you might wish to set this to `true` to get the benefits of
|
||||
preserving the raw form, but for AST-based stringification of JSDoc types,
|
||||
keep it `false` (the default).
|
||||
|
||||
### `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:
|
||||
|
||||
- `getTokenizers` - Used with `parseComment` (its main core).
|
||||
- `hasSeeWithLink` - A utility to detect if a tag is `@see` and has a `@link`.
|
||||
- `commentHandler` - Used by `eslint-plugin-jsdoc`.
|
||||
- `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`.
|
||||
- `jsdocTypeVisitorKeys` - [VisitorKeys](https://github.com/eslint/eslint-visitor-keys)
|
||||
for `jsdoc-type-pratt-parser`.
|
||||
- `defaultNoTypes` = The tags which allow no types by default:
|
||||
`default`, `defaultvalue`, `description`, `example`, `file`,
|
||||
`fileoverview`, `license`, `overview`, `see`, `summary`
|
||||
- `defaultNoNames` - The tags which allow no names by default:
|
||||
`access`, `author`, `default`, `defaultvalue`, `description`, `example`,
|
||||
`exception`, `file`, `fileoverview`, `kind`, `license`, `overview`,
|
||||
`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 the following visitable properties:
|
||||
|
||||
1. `descriptionLines` (an array of `JsdocDescriptionLine` for multiline
|
||||
descriptions).
|
||||
2. `tags` (an array of `JsdocTag`; see below)
|
||||
3. `inlineTags` (an array of `JsdocInlineTag`; see below)
|
||||
|
||||
Has the following custom non-visitable property:
|
||||
|
||||
1. `delimiterLineBreak` - A string containing any line break after `delimiter`.
|
||||
2. `lastDescriptionLine` - A number
|
||||
3. `endLine` - A number representing the line number with `end`/`terminal`
|
||||
4. `descriptionStartLine` - A 0+ number indicating the line where any
|
||||
description begins
|
||||
5. `descriptionEndLine` - A 0+ number indicating the line where the description
|
||||
ends
|
||||
6. `hasPreterminalDescription` - Set to 0 or 1. On if has a block description
|
||||
on the same line as the terminal `*/`.
|
||||
7. `hasPreterminalTagDescription` - Set to 0 or 1. On if has a tag description
|
||||
on the same line as the terminal `*/`.
|
||||
8. `preterminalLineBreak` - A string containing any line break before `terminal`.
|
||||
|
||||
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. `initial` (from `start`)
|
||||
6. `terminal` (from `end`)
|
||||
|
||||
### `JsdocTag`
|
||||
|
||||
Has the following 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. `typeLines` (an array of `JsdocTypeLine` for multiline type strings)
|
||||
3. `descriptionLines` (an array of `JsdocDescriptionLine` for multiline
|
||||
descriptions)
|
||||
4. `inlineTags` (an array of `JsdocInlineTag`)
|
||||
|
||||
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` and `start` to
|
||||
`initial`):
|
||||
|
||||
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. `initial` - Renamed from `start` to avoid potential conflicts with
|
||||
Acorn-style parser processing tools
|
||||
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. `initial` (from `start`)
|
||||
4. `description`
|
||||
|
||||
### `JsdocTypeLine`
|
||||
|
||||
No visitable properties.
|
||||
|
||||
May also have the following non-visitable properties from `comment-parser`:
|
||||
|
||||
1. `delimiter`
|
||||
2. `postDelimiter`
|
||||
3. `initial` (from `start`)
|
||||
4. `rawType` - Renamed from `comment-parser` to avoid a conflict. See
|
||||
explanation under `JsdocTag`
|
||||
|
||||
### `JsdocInlineTag`
|
||||
|
||||
No visitable properties.
|
||||
|
||||
Has the following non-visitable properties:
|
||||
|
||||
1. `format`: 'pipe' | 'plain' | 'prefix' | 'space'. These follow the styles of [link](https://jsdoc.app/tags-inline-link.html) or [tutorial](https://jsdoc.app/tags-inline-tutorial.html).
|
||||
1. `pipe`: `{@link namepathOrURL|link text}`
|
||||
2. `plain`: `{@link namepathOrURL}`
|
||||
3. `prefix`: `[link text]{@link namepathOrURL}`
|
||||
4. `space`: `{@link namepathOrURL link text (after the first space)}`
|
||||
2. `namepathOrURL`: string
|
||||
3. `tag`: string. The standard allows `tutorial` or `link`
|
||||
4. `text`: string
|
||||
|
||||
## 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.
|
||||
|
||||
You can get a sense of the structure of these types using the parser's
|
||||
[tester](https://jsdoc-type-pratt-parser.github.io/jsdoc-type-pratt-parser/).
|
||||
|
||||
## Installation
|
||||
|
||||
```shell
|
||||
npm i @es-joy/jsdoccomment
|
||||
```
|
||||
|
||||
## Changelog
|
||||
|
||||
The changelog can be found on the [CHANGES.md](https://github.com/es-joy/jsdoccomment/blob/main/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/jsdoccomment/graphs/contributors).
|
||||
|
||||
MIT License, see the included [LICENSE-MIT.txt](https://github.com/es-joy/jsdoccomment/blob/main/LICENSE-MIT.txt) file.
|
||||
|
||||
## To-dos
|
||||
|
||||
1. Get complete code coverage
|
||||
1. Given that `esquery` expects a `right` property to search for `>` (the
|
||||
child selector), we should perhaps insist, for example, that params are
|
||||
the child property for `JsdocBlock` or such. Where `:has()` is currently
|
||||
needed, one could thus instead just use `>`.
|
||||
1. Might add `trailing` for `JsdocBlock` to know whether it is followed by a
|
||||
line break or what not; `comment-parser` does not provide, however
|
||||
1. Fix and properly utilize `indent` argument (challenging for
|
||||
`eslint-plugin-jsdoc` but needed for `jsdoc-eslint-parser` stringifiers
|
||||
to be more faithful); should also then use the proposed `trailing` as well
|
||||
1333
node_modules/@es-joy/jsdoccomment/dist/index.cjs.cjs
generated
vendored
Normal file
1333
node_modules/@es-joy/jsdoccomment/dist/index.cjs.cjs
generated
vendored
Normal file
File diff suppressed because it is too large
Load Diff
361
node_modules/@es-joy/jsdoccomment/dist/index.d.ts
generated
vendored
Normal file
361
node_modules/@es-joy/jsdoccomment/dist/index.d.ts
generated
vendored
Normal file
@ -0,0 +1,361 @@
|
||||
import * as comment_parser from 'comment-parser';
|
||||
import * as jsdoc_type_pratt_parser from 'jsdoc-type-pratt-parser';
|
||||
export * from 'jsdoc-type-pratt-parser';
|
||||
export { visitorKeys as jsdocTypeVisitorKeys } from 'jsdoc-type-pratt-parser';
|
||||
import * as _typescript_eslint_types from '@typescript-eslint/types';
|
||||
import * as estree from 'estree';
|
||||
import * as eslint from 'eslint';
|
||||
|
||||
type JsdocTypeLine = {
|
||||
delimiter: string;
|
||||
postDelimiter: string;
|
||||
rawType: string;
|
||||
initial: string;
|
||||
type: 'JsdocTypeLine';
|
||||
};
|
||||
type JsdocDescriptionLine = {
|
||||
delimiter: string;
|
||||
description: string;
|
||||
postDelimiter: string;
|
||||
initial: string;
|
||||
type: 'JsdocDescriptionLine';
|
||||
};
|
||||
type JsdocInlineTagNoType = {
|
||||
format: 'pipe' | 'plain' | 'prefix' | 'space';
|
||||
namepathOrURL: string;
|
||||
tag: string;
|
||||
text: string;
|
||||
};
|
||||
type JsdocInlineTag = JsdocInlineTagNoType & {
|
||||
type: 'JsdocInlineTag';
|
||||
};
|
||||
type JsdocTag = {
|
||||
delimiter: string;
|
||||
description: string;
|
||||
descriptionLines: JsdocDescriptionLine[];
|
||||
initial: string;
|
||||
inlineTags: JsdocInlineTag[];
|
||||
name: string;
|
||||
postDelimiter: string;
|
||||
postName: string;
|
||||
postTag: string;
|
||||
postType: string;
|
||||
rawType: string;
|
||||
parsedType: jsdoc_type_pratt_parser.RootResult | null;
|
||||
tag: string;
|
||||
type: 'JsdocTag';
|
||||
typeLines: JsdocTypeLine[];
|
||||
};
|
||||
type Integer = number;
|
||||
type JsdocBlock = {
|
||||
delimiter: string;
|
||||
delimiterLineBreak: string;
|
||||
description: string;
|
||||
descriptionEndLine?: Integer;
|
||||
descriptionLines: JsdocDescriptionLine[];
|
||||
descriptionStartLine?: Integer;
|
||||
hasPreterminalDescription: 0 | 1;
|
||||
hasPreterminalTagDescription?: 1;
|
||||
initial: string;
|
||||
inlineTags: JsdocInlineTag[];
|
||||
lastDescriptionLine?: Integer;
|
||||
endLine: Integer;
|
||||
lineEnd: string;
|
||||
postDelimiter: string;
|
||||
tags: JsdocTag[];
|
||||
terminal: string;
|
||||
preterminalLineBreak: string;
|
||||
type: 'JsdocBlock';
|
||||
};
|
||||
/**
|
||||
* Converts comment parser AST to ESTree format.
|
||||
* @param {import('.').JsdocBlockWithInline} jsdoc
|
||||
* @param {import('jsdoc-type-pratt-parser').ParseMode} mode
|
||||
* @param {object} opts
|
||||
* @param {'compact'|'preserve'} [opts.spacing] By default, empty lines are
|
||||
* compacted; set to 'preserve' to preserve empty comment lines.
|
||||
* @param {boolean} [opts.throwOnTypeParsingErrors]
|
||||
* @returns {JsdocBlock}
|
||||
*/
|
||||
declare function commentParserToESTree(
|
||||
jsdoc: JsdocBlockWithInline,
|
||||
mode: jsdoc_type_pratt_parser.ParseMode,
|
||||
{
|
||||
spacing,
|
||||
throwOnTypeParsingErrors,
|
||||
}?: {
|
||||
spacing?: 'compact' | 'preserve';
|
||||
throwOnTypeParsingErrors?: boolean;
|
||||
},
|
||||
): JsdocBlock;
|
||||
declare namespace jsdocVisitorKeys {
|
||||
let JsdocBlock: string[];
|
||||
let JsdocDescriptionLine: any[];
|
||||
let JsdocTypeLine: any[];
|
||||
let JsdocTag: string[];
|
||||
let JsdocInlineTag: any[];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {{[name: string]: any}} settings
|
||||
* @returns {import('.').CommentHandler}
|
||||
*/
|
||||
declare function commentHandler(settings: { [name: string]: any }): CommentHandler;
|
||||
|
||||
/**
|
||||
* @todo convert for use by escodegen (until may be patched to support
|
||||
* custom entries?).
|
||||
* @param {import('./commentParserToESTree').JsdocBlock|
|
||||
* import('./commentParserToESTree').JsdocDescriptionLine|
|
||||
* import('./commentParserToESTree').JsdocTypeLine|
|
||||
* import('./commentParserToESTree').JsdocTag|
|
||||
* import('./commentParserToESTree').JsdocInlineTag|
|
||||
* import('jsdoc-type-pratt-parser').RootResult
|
||||
* } node
|
||||
* @param {import('.').ESTreeToStringOptions} opts
|
||||
* @throws {Error}
|
||||
* @returns {string}
|
||||
*/
|
||||
declare function estreeToString(
|
||||
node:
|
||||
| JsdocBlock
|
||||
| JsdocDescriptionLine
|
||||
| JsdocTypeLine
|
||||
| JsdocTag
|
||||
| JsdocInlineTag
|
||||
| jsdoc_type_pratt_parser.RootResult,
|
||||
opts?: ESTreeToStringOptions,
|
||||
): string;
|
||||
|
||||
type Token =
|
||||
| eslint.AST.Token
|
||||
| estree.Comment
|
||||
| {
|
||||
type: eslint.AST.TokenType | 'Line' | 'Block' | 'Shebang';
|
||||
range: [number, number];
|
||||
value: string;
|
||||
};
|
||||
type ESLintOrTSNode = eslint.Rule.Node | _typescript_eslint_types.TSESTree.Node;
|
||||
type int = number;
|
||||
/**
|
||||
* Reduces the provided node to the appropriate node for evaluating
|
||||
* JSDoc comment status.
|
||||
*
|
||||
* @param {ESLintOrTSNode} node An AST node.
|
||||
* @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode.
|
||||
* @returns {ESLintOrTSNode} The AST node that
|
||||
* can be evaluated for appropriate JSDoc comments.
|
||||
*/
|
||||
declare function getReducedASTNode(node: ESLintOrTSNode, sourceCode: eslint.SourceCode): ESLintOrTSNode;
|
||||
/**
|
||||
* Retrieves the JSDoc comment for a given node.
|
||||
*
|
||||
* @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode
|
||||
* @param {import('eslint').Rule.Node} node The AST node to get
|
||||
* the comment for.
|
||||
* @param {{maxLines: int, minLines: int, [name: string]: any}} settings The
|
||||
* settings in context
|
||||
* @returns {Token|null} The Block comment
|
||||
* token containing the JSDoc comment for the given node or
|
||||
* null if not found.
|
||||
* @public
|
||||
*/
|
||||
declare function getJSDocComment(
|
||||
sourceCode: eslint.SourceCode,
|
||||
node: eslint.Rule.Node,
|
||||
settings: {
|
||||
maxLines: int;
|
||||
minLines: int;
|
||||
[name: string]: any;
|
||||
},
|
||||
): Token | null;
|
||||
/**
|
||||
* Retrieves the comment preceding a given node.
|
||||
*
|
||||
* @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode
|
||||
* @param {ESLintOrTSNode} node The AST node to get
|
||||
* the comment for.
|
||||
* @param {{maxLines: int, minLines: int, [name: string]: any}} settings The
|
||||
* settings in context
|
||||
* @returns {Token|null} The Block comment
|
||||
* token containing the JSDoc comment for the given node or
|
||||
* null if not found.
|
||||
* @public
|
||||
*/
|
||||
declare function getNonJsdocComment(
|
||||
sourceCode: eslint.SourceCode,
|
||||
node: ESLintOrTSNode,
|
||||
settings: {
|
||||
maxLines: int;
|
||||
minLines: int;
|
||||
[name: string]: any;
|
||||
},
|
||||
): Token | null;
|
||||
/**
|
||||
* @param {(ESLintOrTSNode|import('estree').Comment) & {
|
||||
* declaration?: any,
|
||||
* decorators?: any[],
|
||||
* parent?: import('eslint').Rule.Node & {
|
||||
* decorators?: any[]
|
||||
* }
|
||||
* }} node
|
||||
* @returns {import('@typescript-eslint/types').TSESTree.Decorator|undefined}
|
||||
*/
|
||||
declare function getDecorator(
|
||||
node: (ESLintOrTSNode | estree.Comment) & {
|
||||
declaration?: any;
|
||||
decorators?: any[];
|
||||
parent?: eslint.Rule.Node & {
|
||||
decorators?: any[];
|
||||
};
|
||||
},
|
||||
): _typescript_eslint_types.TSESTree.Decorator | undefined;
|
||||
/**
|
||||
* Checks for the presence of a JSDoc comment for the given node and returns it.
|
||||
*
|
||||
* @param {ESLintOrTSNode} astNode The AST node to get
|
||||
* the comment for.
|
||||
* @param {import('eslint').SourceCode} sourceCode
|
||||
* @param {{maxLines: int, minLines: int, [name: string]: any}} settings
|
||||
* @param {{nonJSDoc?: boolean}} [opts]
|
||||
* @returns {Token|null} The Block comment token containing the JSDoc comment
|
||||
* for the given node or null if not found.
|
||||
*/
|
||||
declare function findJSDocComment(
|
||||
astNode: ESLintOrTSNode,
|
||||
sourceCode: eslint.SourceCode,
|
||||
settings: {
|
||||
maxLines: int;
|
||||
minLines: int;
|
||||
[name: string]: any;
|
||||
},
|
||||
opts?: {
|
||||
nonJSDoc?: boolean;
|
||||
},
|
||||
): Token | null;
|
||||
/**
|
||||
* Checks for the presence of a comment following the given node and
|
||||
* returns it.
|
||||
*
|
||||
* This method is experimental.
|
||||
*
|
||||
* @param {import('eslint').SourceCode} sourceCode
|
||||
* @param {ESLintOrTSNode} astNode The AST node to get
|
||||
* the comment for.
|
||||
* @returns {Token|null} The comment token containing the comment
|
||||
* for the given node or null if not found.
|
||||
*/
|
||||
declare function getFollowingComment(sourceCode: eslint.SourceCode, astNode: ESLintOrTSNode): Token | null;
|
||||
|
||||
declare function hasSeeWithLink(spec: comment_parser.Spec): boolean;
|
||||
declare const defaultNoTypes: string[];
|
||||
declare const defaultNoNames: string[];
|
||||
/**
|
||||
* Can't import `comment-parser/es6/parser/tokenizers/index.js`,
|
||||
* so we redefine here.
|
||||
*/
|
||||
type CommentParserTokenizer = (spec: comment_parser.Spec) => comment_parser.Spec;
|
||||
/**
|
||||
* Can't import `comment-parser/es6/parser/tokenizers/index.js`,
|
||||
* so we redefine here.
|
||||
* @typedef {(spec: import('comment-parser').Spec) =>
|
||||
* import('comment-parser').Spec} CommentParserTokenizer
|
||||
*/
|
||||
/**
|
||||
* @param {object} [cfg]
|
||||
* @param {string[]} [cfg.noTypes]
|
||||
* @param {string[]} [cfg.noNames]
|
||||
* @returns {CommentParserTokenizer[]}
|
||||
*/
|
||||
declare function getTokenizers({
|
||||
noTypes,
|
||||
noNames,
|
||||
}?: {
|
||||
noTypes?: string[];
|
||||
noNames?: string[];
|
||||
}): CommentParserTokenizer[];
|
||||
/**
|
||||
* Accepts a comment token or complete comment string and converts it into
|
||||
* `comment-parser` AST.
|
||||
* @param {string | {value: string}} commentOrNode
|
||||
* @param {string} [indent] Whitespace
|
||||
* @returns {import('.').JsdocBlockWithInline}
|
||||
*/
|
||||
declare function parseComment(
|
||||
commentOrNode:
|
||||
| string
|
||||
| {
|
||||
value: string;
|
||||
},
|
||||
indent?: string,
|
||||
): JsdocBlockWithInline;
|
||||
|
||||
/**
|
||||
* Splits the `{@prefix}` from remaining `Spec.lines[].token.description`
|
||||
* into the `inlineTags` tokens, and populates `spec.inlineTags`
|
||||
* @param {import('comment-parser').Block} block
|
||||
* @returns {import('.').JsdocBlockWithInline}
|
||||
*/
|
||||
declare function parseInlineTags(block: comment_parser.Block): JsdocBlockWithInline;
|
||||
|
||||
type InlineTag = JsdocInlineTagNoType & {
|
||||
start: number;
|
||||
end: number;
|
||||
};
|
||||
type JsdocTagWithInline = comment_parser.Spec & {
|
||||
line?: Integer;
|
||||
inlineTags: (JsdocInlineTagNoType & {
|
||||
line?: Integer;
|
||||
})[];
|
||||
};
|
||||
/**
|
||||
* Expands on comment-parser's `Block` interface.
|
||||
*/
|
||||
type JsdocBlockWithInline = {
|
||||
description: string;
|
||||
source: comment_parser.Line[];
|
||||
problems: comment_parser.Problem[];
|
||||
tags: JsdocTagWithInline[];
|
||||
inlineTags: (JsdocInlineTagNoType & {
|
||||
line?: Integer;
|
||||
})[];
|
||||
};
|
||||
type ESTreeToStringOptions = {
|
||||
preferRawType?: boolean;
|
||||
};
|
||||
type CommentHandler = (commentSelector: string, jsdoc: JsdocBlockWithInline) => boolean;
|
||||
|
||||
export {
|
||||
type CommentHandler,
|
||||
type CommentParserTokenizer,
|
||||
type ESLintOrTSNode,
|
||||
type ESTreeToStringOptions,
|
||||
type InlineTag,
|
||||
type Integer,
|
||||
JsdocBlock,
|
||||
type JsdocBlockWithInline,
|
||||
JsdocDescriptionLine,
|
||||
JsdocInlineTag,
|
||||
type JsdocInlineTagNoType,
|
||||
JsdocTag,
|
||||
type JsdocTagWithInline,
|
||||
JsdocTypeLine,
|
||||
type Token,
|
||||
commentHandler,
|
||||
commentParserToESTree,
|
||||
defaultNoNames,
|
||||
defaultNoTypes,
|
||||
estreeToString,
|
||||
findJSDocComment,
|
||||
getDecorator,
|
||||
getFollowingComment,
|
||||
getJSDocComment,
|
||||
getNonJsdocComment,
|
||||
getReducedASTNode,
|
||||
getTokenizers,
|
||||
hasSeeWithLink,
|
||||
type int,
|
||||
jsdocVisitorKeys,
|
||||
parseComment,
|
||||
parseInlineTags,
|
||||
};
|
||||
106
node_modules/@es-joy/jsdoccomment/package.json
generated
vendored
Normal file
106
node_modules/@es-joy/jsdoccomment/package.json
generated
vendored
Normal file
@ -0,0 +1,106 @@
|
||||
{
|
||||
"name": "@es-joy/jsdoccomment",
|
||||
"version": "0.46.0",
|
||||
"author": "Brett Zamir <brettz9@yahoo.com>",
|
||||
"contributors": [],
|
||||
"description": "Maintained replacement for ESLint's deprecated SourceCode#getJSDocComment along with other jsdoc utilities",
|
||||
"license": "MIT",
|
||||
"keywords": [
|
||||
"ast",
|
||||
"comment",
|
||||
"estree",
|
||||
"jsdoc",
|
||||
"parser",
|
||||
"eslint",
|
||||
"sourcecode"
|
||||
],
|
||||
"type": "module",
|
||||
"types": "./dist/index.d.ts",
|
||||
"exports": {
|
||||
"types": "./dist/index.d.ts",
|
||||
"import": "./src/index.js",
|
||||
"require": "./dist/index.cjs.cjs"
|
||||
},
|
||||
"browserslist": [
|
||||
"cover 100%"
|
||||
],
|
||||
"typedocOptions": {
|
||||
"dmtLinksService": {
|
||||
"GitHub": "https://github.com/es-joy/jsdoccomment",
|
||||
"NPM": "https://www.npmjs.com/package/@es-joy/jsdoccomment"
|
||||
}
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "git+https://github.com/es-joy/jsdoccomment.git"
|
||||
},
|
||||
"bugs": {
|
||||
"url": "https://github.com/es-joy/jsdoccomment/issues"
|
||||
},
|
||||
"homepage": "https://github.com/es-joy/jsdoccomment",
|
||||
"engines": {
|
||||
"node": ">=16"
|
||||
},
|
||||
"dependencies": {
|
||||
"comment-parser": "1.4.1",
|
||||
"esquery": "^1.6.0",
|
||||
"jsdoc-type-pratt-parser": "~4.0.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@babel/core": "^7.24.7",
|
||||
"@babel/plugin-syntax-class-properties": "^7.12.13",
|
||||
"@babel/preset-env": "^7.24.7",
|
||||
"@brettz9/eslint-plugin": "^1.0.4",
|
||||
"@rollup/plugin-babel": "^6.0.4",
|
||||
"@types/eslint": "^8.56.10",
|
||||
"@types/esquery": "^1.5.4",
|
||||
"@types/estraverse": "^5.1.7",
|
||||
"@types/estree": "^1.0.5",
|
||||
"@typescript-eslint/types": "^7.16.0",
|
||||
"@typescript-eslint/visitor-keys": "^7.16.0",
|
||||
"@typhonjs-build-test/esm-d-ts": "0.3.0-next.1",
|
||||
"@typhonjs-typedoc/typedoc-pkg": "^0.0.5",
|
||||
"@vitest/coverage-v8": "^2.0.1",
|
||||
"@vitest/ui": "^2.0.1",
|
||||
"eslint": "^8.56.0",
|
||||
"eslint-config-ash-nazg": "35.3.0",
|
||||
"eslint-config-standard": "^17.1.0",
|
||||
"eslint-plugin-array-func": "^4.0.0",
|
||||
"eslint-plugin-compat": "^4.2.0",
|
||||
"eslint-plugin-eslint-comments": "^3.2.0",
|
||||
"eslint-plugin-html": "^7.1.0",
|
||||
"eslint-plugin-import": "^2.29.1",
|
||||
"eslint-plugin-jsdoc": "^48.0.4",
|
||||
"eslint-plugin-markdown": "^3.0.1",
|
||||
"eslint-plugin-n": "^16.6.2",
|
||||
"eslint-plugin-no-unsanitized": "^4.0.2",
|
||||
"eslint-plugin-no-use-extend-native": "^0.5.0",
|
||||
"eslint-plugin-promise": "^6.1.1",
|
||||
"eslint-plugin-sonarjs": "^0.23.0",
|
||||
"eslint-plugin-unicorn": "^50.0.1",
|
||||
"espree": "^10.1.0",
|
||||
"estraverse": "^5.3.0",
|
||||
"rollup": "^4.18.1",
|
||||
"typescript": "^5.5.3",
|
||||
"typescript-eslint": "^7.16.0",
|
||||
"vitest": "^2.0.1"
|
||||
},
|
||||
"files": [
|
||||
"/dist",
|
||||
"/src",
|
||||
"CHANGES.md",
|
||||
"LICENSE-MIT.txt"
|
||||
],
|
||||
"scripts": {
|
||||
"build": "rollup -c && npm run types",
|
||||
"docs": "typedoc-pkg --api-link es",
|
||||
"eslint": "eslint --ext=js,cjs,md,html .",
|
||||
"lint": "npm run eslint --",
|
||||
"open": "open ./coverage/index.html",
|
||||
"test": "npm run lint && npm run build && npm run test-ui",
|
||||
"test-ui": "vitest --ui --coverage",
|
||||
"test-cov": "vitest --coverage",
|
||||
"tsc": "tsc",
|
||||
"types": "esm-d-ts gen ./src/index.js --output ./dist/index.d.ts"
|
||||
}
|
||||
}
|
||||
39
node_modules/@es-joy/jsdoccomment/src/commentHandler.js
generated
vendored
Normal file
39
node_modules/@es-joy/jsdoccomment/src/commentHandler.js
generated
vendored
Normal file
@ -0,0 +1,39 @@
|
||||
import esquery from 'esquery';
|
||||
|
||||
import {
|
||||
visitorKeys as jsdocTypePrattParserVisitorKeys
|
||||
} from 'jsdoc-type-pratt-parser';
|
||||
|
||||
import {
|
||||
commentParserToESTree, jsdocVisitorKeys
|
||||
} from './commentParserToESTree.js';
|
||||
|
||||
/**
|
||||
* @param {{[name: string]: any}} settings
|
||||
* @returns {import('.').CommentHandler}
|
||||
*/
|
||||
const commentHandler = (settings) => {
|
||||
/**
|
||||
* @type {import('.').CommentHandler}
|
||||
*/
|
||||
return (commentSelector, jsdoc) => {
|
||||
const {mode} = settings;
|
||||
|
||||
const selector = esquery.parse(commentSelector);
|
||||
|
||||
const ast = commentParserToESTree(jsdoc, mode);
|
||||
|
||||
const _ast = /** @type {unknown} */ (ast);
|
||||
|
||||
return esquery.matches(/** @type {import('estree').Node} */ (
|
||||
_ast
|
||||
), selector, undefined, {
|
||||
visitorKeys: {
|
||||
...jsdocTypePrattParserVisitorKeys,
|
||||
...jsdocVisitorKeys
|
||||
}
|
||||
});
|
||||
};
|
||||
};
|
||||
|
||||
export {commentHandler};
|
||||
504
node_modules/@es-joy/jsdoccomment/src/commentParserToESTree.js
generated
vendored
Normal file
504
node_modules/@es-joy/jsdoccomment/src/commentParserToESTree.js
generated
vendored
Normal file
@ -0,0 +1,504 @@
|
||||
import {parse as jsdocTypePrattParse} from 'jsdoc-type-pratt-parser';
|
||||
|
||||
/**
|
||||
* Removes initial and ending brackets from `rawType`
|
||||
* @param {JsdocTypeLine[]|JsdocTag} container
|
||||
* @param {boolean} [isArr]
|
||||
* @returns {void}
|
||||
*/
|
||||
const stripEncapsulatingBrackets = (container, isArr) => {
|
||||
if (isArr) {
|
||||
const firstItem = /** @type {JsdocTypeLine[]} */ (container)[0];
|
||||
firstItem.rawType = firstItem.rawType.replace(
|
||||
/^\{/u, ''
|
||||
);
|
||||
|
||||
const lastItem = /** @type {JsdocTypeLine} */ (
|
||||
/** @type {JsdocTypeLine[]} */ (
|
||||
container
|
||||
).at(-1)
|
||||
);
|
||||
lastItem.rawType = lastItem.rawType.replace(/\}$/u, '');
|
||||
|
||||
return;
|
||||
}
|
||||
/** @type {JsdocTag} */ (container).rawType =
|
||||
/** @type {JsdocTag} */ (container).rawType.replace(
|
||||
/^\{/u, ''
|
||||
).replace(/\}$/u, '');
|
||||
};
|
||||
|
||||
/**
|
||||
* @typedef {{
|
||||
* delimiter: string,
|
||||
* postDelimiter: string,
|
||||
* rawType: string,
|
||||
* initial: string,
|
||||
* type: "JsdocTypeLine"
|
||||
* }} JsdocTypeLine
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {{
|
||||
* delimiter: string,
|
||||
* description: string,
|
||||
* postDelimiter: string,
|
||||
* initial: string,
|
||||
* type: "JsdocDescriptionLine"
|
||||
* }} JsdocDescriptionLine
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {{
|
||||
* format: 'pipe' | 'plain' | 'prefix' | 'space',
|
||||
* namepathOrURL: string,
|
||||
* tag: string,
|
||||
* text: string,
|
||||
* }} JsdocInlineTagNoType
|
||||
*/
|
||||
/**
|
||||
* @typedef {JsdocInlineTagNoType & {
|
||||
* type: "JsdocInlineTag"
|
||||
* }} JsdocInlineTag
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {{
|
||||
* delimiter: string,
|
||||
* description: string,
|
||||
* descriptionLines: JsdocDescriptionLine[],
|
||||
* initial: string,
|
||||
* inlineTags: JsdocInlineTag[]
|
||||
* name: string,
|
||||
* postDelimiter: string,
|
||||
* postName: string,
|
||||
* postTag: string,
|
||||
* postType: string,
|
||||
* rawType: string,
|
||||
* parsedType: import('jsdoc-type-pratt-parser').RootResult|null
|
||||
* tag: string,
|
||||
* type: "JsdocTag",
|
||||
* typeLines: JsdocTypeLine[],
|
||||
* }} JsdocTag
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {number} Integer
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {{
|
||||
* delimiter: string,
|
||||
* delimiterLineBreak: string,
|
||||
* description: string,
|
||||
* descriptionEndLine?: Integer,
|
||||
* descriptionLines: JsdocDescriptionLine[],
|
||||
* descriptionStartLine?: Integer,
|
||||
* hasPreterminalDescription: 0|1,
|
||||
* hasPreterminalTagDescription?: 1,
|
||||
* initial: string,
|
||||
* inlineTags: JsdocInlineTag[]
|
||||
* lastDescriptionLine?: Integer,
|
||||
* endLine: Integer,
|
||||
* lineEnd: string,
|
||||
* postDelimiter: string,
|
||||
* tags: JsdocTag[],
|
||||
* terminal: string,
|
||||
* preterminalLineBreak: string,
|
||||
* type: "JsdocBlock",
|
||||
* }} JsdocBlock
|
||||
*/
|
||||
|
||||
/**
|
||||
* @param {object} cfg
|
||||
* @param {string} cfg.text
|
||||
* @param {string} cfg.tag
|
||||
* @param {'pipe' | 'plain' | 'prefix' | 'space'} cfg.format
|
||||
* @param {string} cfg.namepathOrURL
|
||||
* @returns {JsdocInlineTag}
|
||||
*/
|
||||
const inlineTagToAST = ({text, tag, format, namepathOrURL}) => ({
|
||||
text,
|
||||
tag,
|
||||
format,
|
||||
namepathOrURL,
|
||||
type: 'JsdocInlineTag'
|
||||
});
|
||||
|
||||
/**
|
||||
* Converts comment parser AST to ESTree format.
|
||||
* @param {import('.').JsdocBlockWithInline} jsdoc
|
||||
* @param {import('jsdoc-type-pratt-parser').ParseMode} mode
|
||||
* @param {object} opts
|
||||
* @param {'compact'|'preserve'} [opts.spacing] By default, empty lines are
|
||||
* compacted; set to 'preserve' to preserve empty comment lines.
|
||||
* @param {boolean} [opts.throwOnTypeParsingErrors]
|
||||
* @returns {JsdocBlock}
|
||||
*/
|
||||
const commentParserToESTree = (jsdoc, mode, {
|
||||
spacing = 'compact',
|
||||
throwOnTypeParsingErrors = false
|
||||
} = {}) => {
|
||||
/**
|
||||
* Strips brackets from a tag's `rawType` values and adds `parsedType`
|
||||
* @param {JsdocTag} lastTag
|
||||
* @returns {void}
|
||||
*/
|
||||
const cleanUpLastTag = (lastTag) => {
|
||||
// Strip out `}` that encapsulates and is not part of
|
||||
// the type
|
||||
stripEncapsulatingBrackets(lastTag);
|
||||
|
||||
if (lastTag.typeLines.length) {
|
||||
stripEncapsulatingBrackets(lastTag.typeLines, true);
|
||||
}
|
||||
|
||||
// Remove single empty line description.
|
||||
if (lastTag.descriptionLines.length === 1 &&
|
||||
lastTag.descriptionLines[0].description === '') {
|
||||
lastTag.descriptionLines.length = 0;
|
||||
}
|
||||
|
||||
// With even a multiline type now in full, add parsing
|
||||
let parsedType = null;
|
||||
|
||||
try {
|
||||
parsedType = jsdocTypePrattParse(lastTag.rawType, mode);
|
||||
} catch (err) {
|
||||
// Ignore
|
||||
if (lastTag.rawType && throwOnTypeParsingErrors) {
|
||||
/** @type {Error} */ (
|
||||
err
|
||||
).message = `Tag @${lastTag.tag} with raw type ` +
|
||||
`\`${lastTag.rawType}\` had parsing error: ${
|
||||
/** @type {Error} */ (err).message}`;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
lastTag.parsedType = parsedType;
|
||||
};
|
||||
|
||||
const {source, inlineTags: blockInlineTags} = jsdoc;
|
||||
|
||||
const {tokens: {
|
||||
delimiter: delimiterRoot,
|
||||
lineEnd: lineEndRoot,
|
||||
postDelimiter: postDelimiterRoot,
|
||||
start: startRoot,
|
||||
end: endRoot
|
||||
}} = source[0];
|
||||
|
||||
const endLine = source.length - 1;
|
||||
|
||||
/** @type {JsdocBlock} */
|
||||
const ast = {
|
||||
delimiter: delimiterRoot,
|
||||
delimiterLineBreak: '\n',
|
||||
description: '',
|
||||
|
||||
descriptionLines: [],
|
||||
inlineTags: blockInlineTags.map((t) => inlineTagToAST(t)),
|
||||
|
||||
initial: startRoot,
|
||||
tags: [],
|
||||
// `terminal` will be overwritten if there are other entries
|
||||
terminal: endRoot,
|
||||
preterminalLineBreak: '\n',
|
||||
hasPreterminalDescription: 0,
|
||||
endLine,
|
||||
postDelimiter: postDelimiterRoot,
|
||||
lineEnd: lineEndRoot,
|
||||
|
||||
type: 'JsdocBlock'
|
||||
};
|
||||
|
||||
/**
|
||||
* @type {JsdocTag[]}
|
||||
*/
|
||||
const tags = [];
|
||||
|
||||
/** @type {Integer|undefined} */
|
||||
let lastDescriptionLine;
|
||||
|
||||
/** @type {JsdocTag|null} */
|
||||
let lastTag = null;
|
||||
|
||||
// Tracks when first valid tag description line is seen.
|
||||
let tagDescriptionSeen = false;
|
||||
|
||||
let descLineStateOpen = true;
|
||||
|
||||
source.forEach((info, idx) => {
|
||||
const {tokens} = info;
|
||||
const {
|
||||
delimiter,
|
||||
description,
|
||||
postDelimiter,
|
||||
start: initial,
|
||||
tag,
|
||||
end,
|
||||
type: rawType
|
||||
} = tokens;
|
||||
|
||||
if (!tag && description && descLineStateOpen) {
|
||||
if (ast.descriptionStartLine === undefined) {
|
||||
ast.descriptionStartLine = idx;
|
||||
}
|
||||
ast.descriptionEndLine = idx;
|
||||
}
|
||||
|
||||
if (tag || end) {
|
||||
descLineStateOpen = false;
|
||||
if (lastDescriptionLine === undefined) {
|
||||
lastDescriptionLine = idx;
|
||||
}
|
||||
|
||||
// Clean-up with last tag before end or new tag
|
||||
if (lastTag) {
|
||||
cleanUpLastTag(lastTag);
|
||||
}
|
||||
|
||||
// Stop the iteration when we reach the end
|
||||
// but only when there is no tag earlier in the line
|
||||
// to still process
|
||||
if (end && !tag) {
|
||||
ast.terminal = end;
|
||||
|
||||
// Check if there are any description lines and if not then this is a
|
||||
// one line comment block.
|
||||
const isDelimiterLine = ast.descriptionLines.length === 0 &&
|
||||
delimiter === '/**';
|
||||
|
||||
// Remove delimiter line break for one line comments blocks.
|
||||
if (isDelimiterLine) {
|
||||
ast.delimiterLineBreak = '';
|
||||
}
|
||||
|
||||
if (description) {
|
||||
// Remove terminal line break at end when description is defined.
|
||||
if (ast.terminal === '*/') {
|
||||
ast.preterminalLineBreak = '';
|
||||
}
|
||||
|
||||
if (lastTag) {
|
||||
ast.hasPreterminalTagDescription = 1;
|
||||
} else {
|
||||
ast.hasPreterminalDescription = 1;
|
||||
}
|
||||
|
||||
const holder = lastTag || ast;
|
||||
holder.description += (holder.description ? '\n' : '') + description;
|
||||
|
||||
// Do not include `delimiter` / `postDelimiter` for opening
|
||||
// delimiter line.
|
||||
|
||||
holder.descriptionLines.push({
|
||||
delimiter: isDelimiterLine ? '' : delimiter,
|
||||
description,
|
||||
postDelimiter: isDelimiterLine ? '' : postDelimiter,
|
||||
initial,
|
||||
type: 'JsdocDescriptionLine'
|
||||
});
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
const {
|
||||
// eslint-disable-next-line no-unused-vars -- Discarding
|
||||
end: ed,
|
||||
delimiter: de,
|
||||
postDelimiter: pd,
|
||||
start: init,
|
||||
...tkns
|
||||
} = tokens;
|
||||
|
||||
if (!tokens.name) {
|
||||
let i = 1;
|
||||
while (source[idx + i]) {
|
||||
const {tokens: {
|
||||
name,
|
||||
postName,
|
||||
postType,
|
||||
tag: tg
|
||||
}} = source[idx + i];
|
||||
if (tg) {
|
||||
break;
|
||||
}
|
||||
if (name) {
|
||||
tkns.postType = postType;
|
||||
tkns.name = name;
|
||||
tkns.postName = postName;
|
||||
break;
|
||||
}
|
||||
i++;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @type {JsdocInlineTag[]}
|
||||
*/
|
||||
let tagInlineTags = [];
|
||||
if (tag) {
|
||||
// Assuming the tags from `source` are in the same order as `jsdoc.tags`
|
||||
// we can use the `tags` length as index into the parser result tags.
|
||||
tagInlineTags =
|
||||
/**
|
||||
* @type {import('comment-parser').Spec & {
|
||||
* inlineTags: JsdocInlineTagNoType[]
|
||||
* }}
|
||||
*/ (
|
||||
jsdoc.tags[tags.length]
|
||||
).inlineTags.map(
|
||||
(t) => inlineTagToAST(t)
|
||||
);
|
||||
}
|
||||
|
||||
/** @type {JsdocTag} */
|
||||
const tagObj = {
|
||||
...tkns,
|
||||
initial: endLine ? init : '',
|
||||
postDelimiter: lastDescriptionLine ? pd : '',
|
||||
delimiter: lastDescriptionLine ? de : '',
|
||||
descriptionLines: [],
|
||||
inlineTags: tagInlineTags,
|
||||
parsedType: null,
|
||||
rawType: '',
|
||||
type: 'JsdocTag',
|
||||
typeLines: []
|
||||
};
|
||||
tagObj.tag = tagObj.tag.replace(/^@/u, '');
|
||||
|
||||
lastTag = tagObj;
|
||||
tagDescriptionSeen = false;
|
||||
|
||||
tags.push(tagObj);
|
||||
}
|
||||
|
||||
if (rawType) {
|
||||
// Will strip rawType brackets after this tag
|
||||
/** @type {JsdocTag} */ (lastTag).typeLines.push(
|
||||
/** @type {JsdocTag} */ (lastTag).typeLines.length
|
||||
? {
|
||||
delimiter,
|
||||
postDelimiter,
|
||||
rawType,
|
||||
initial,
|
||||
type: 'JsdocTypeLine'
|
||||
}
|
||||
: {
|
||||
delimiter: '',
|
||||
postDelimiter: '',
|
||||
rawType,
|
||||
initial: '',
|
||||
type: 'JsdocTypeLine'
|
||||
}
|
||||
);
|
||||
/** @type {JsdocTag} */ (lastTag).rawType += /** @type {JsdocTag} */ (
|
||||
lastTag
|
||||
).rawType
|
||||
? '\n' + rawType
|
||||
: rawType;
|
||||
}
|
||||
|
||||
// In `compact` mode skip processing if `description` is an empty string
|
||||
// unless lastTag is being processed.
|
||||
//
|
||||
// In `preserve` mode process when `description` is not the `empty string
|
||||
// or the `delimiter` is not `/**` ensuring empty lines are preserved.
|
||||
if (((spacing === 'compact' && description) || lastTag) ||
|
||||
(spacing === 'preserve' && (description || delimiter !== '/**'))) {
|
||||
const holder = lastTag || ast;
|
||||
|
||||
// Check if there are any description lines and if not then this is a
|
||||
// multi-line comment block with description on 0th line. Treat
|
||||
// `delimiter` / `postDelimiter` / `initial` as being on a new line.
|
||||
const isDelimiterLine = holder.descriptionLines.length === 0 &&
|
||||
delimiter === '/**';
|
||||
|
||||
// Remove delimiter line break for one line comments blocks.
|
||||
if (isDelimiterLine) {
|
||||
ast.delimiterLineBreak = '';
|
||||
}
|
||||
|
||||
// Track when the first description line is seen to avoid adding empty
|
||||
// description lines for tag type lines.
|
||||
tagDescriptionSeen ||= Boolean(lastTag &&
|
||||
(rawType === '' || rawType?.endsWith('}')));
|
||||
|
||||
if (lastTag) {
|
||||
if (tagDescriptionSeen) {
|
||||
// The first tag description line is a continuation after type /
|
||||
// name parsing.
|
||||
const isFirstDescriptionLine = holder.descriptionLines.length === 0;
|
||||
|
||||
// For `compact` spacing must allow through first description line.
|
||||
if ((spacing === 'compact' &&
|
||||
(description || isFirstDescriptionLine)) ||
|
||||
spacing === 'preserve') {
|
||||
holder.descriptionLines.push({
|
||||
delimiter: isFirstDescriptionLine ? '' : delimiter,
|
||||
description,
|
||||
postDelimiter: isFirstDescriptionLine ? '' : postDelimiter,
|
||||
initial: isFirstDescriptionLine ? '' : initial,
|
||||
type: 'JsdocDescriptionLine'
|
||||
});
|
||||
}
|
||||
}
|
||||
} else {
|
||||
holder.descriptionLines.push({
|
||||
delimiter: isDelimiterLine ? '' : delimiter,
|
||||
description,
|
||||
postDelimiter: isDelimiterLine ? '' : postDelimiter,
|
||||
initial: isDelimiterLine ? `` : initial,
|
||||
type: 'JsdocDescriptionLine'
|
||||
});
|
||||
}
|
||||
|
||||
if (!tag) {
|
||||
if (lastTag) {
|
||||
// For `compact` spacing must filter out any empty description lines
|
||||
// after the initial `holder.description` has content.
|
||||
if (tagDescriptionSeen && !(spacing === 'compact' &&
|
||||
holder.description && description === '')) {
|
||||
holder.description += !holder.description
|
||||
? description
|
||||
: '\n' + description;
|
||||
}
|
||||
} else {
|
||||
holder.description += !holder.description
|
||||
? description
|
||||
: '\n' + description;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Clean-up where last line itself has tag content
|
||||
if (end && tag) {
|
||||
ast.terminal = end;
|
||||
ast.hasPreterminalTagDescription = 1;
|
||||
|
||||
// Remove terminal line break at end when tag is defined on last line.
|
||||
if (ast.terminal === '*/') {
|
||||
ast.preterminalLineBreak = '';
|
||||
}
|
||||
|
||||
cleanUpLastTag(/** @type {JsdocTag} */ (lastTag));
|
||||
}
|
||||
});
|
||||
|
||||
ast.lastDescriptionLine = lastDescriptionLine;
|
||||
ast.tags = tags;
|
||||
|
||||
return ast;
|
||||
};
|
||||
|
||||
const jsdocVisitorKeys = {
|
||||
JsdocBlock: ['descriptionLines', 'tags', 'inlineTags'],
|
||||
JsdocDescriptionLine: [],
|
||||
JsdocTypeLine: [],
|
||||
JsdocTag: ['parsedType', 'typeLines', 'descriptionLines', 'inlineTags'],
|
||||
JsdocInlineTag: []
|
||||
};
|
||||
|
||||
export {commentParserToESTree, jsdocVisitorKeys};
|
||||
179
node_modules/@es-joy/jsdoccomment/src/estreeToString.js
generated
vendored
Normal file
179
node_modules/@es-joy/jsdoccomment/src/estreeToString.js
generated
vendored
Normal file
@ -0,0 +1,179 @@
|
||||
import {stringify as prattStringify} from 'jsdoc-type-pratt-parser';
|
||||
|
||||
/** @type {Record<string, Function>} */
|
||||
const stringifiers = {
|
||||
JsdocBlock,
|
||||
|
||||
/**
|
||||
* @param {import('./commentParserToESTree').JsdocDescriptionLine} node
|
||||
* @returns {string}
|
||||
*/
|
||||
JsdocDescriptionLine ({
|
||||
initial, delimiter, postDelimiter, description
|
||||
}) {
|
||||
return `${initial}${delimiter}${postDelimiter}${description}`;
|
||||
},
|
||||
|
||||
/**
|
||||
* @param {import('./commentParserToESTree').JsdocTypeLine} node
|
||||
* @returns {string}
|
||||
*/
|
||||
JsdocTypeLine ({
|
||||
initial, delimiter, postDelimiter, rawType
|
||||
}) {
|
||||
return `${initial}${delimiter}${postDelimiter}${rawType}`;
|
||||
},
|
||||
|
||||
/**
|
||||
* @param {import('./commentParserToESTree').JsdocInlineTag} node
|
||||
*/
|
||||
JsdocInlineTag ({format, namepathOrURL, tag, text}) {
|
||||
return format === 'pipe'
|
||||
? `{@${tag} ${namepathOrURL}|${text}}`
|
||||
: format === 'plain'
|
||||
? `{@${tag} ${namepathOrURL}}`
|
||||
: format === 'prefix'
|
||||
? `[${text}]{@${tag} ${namepathOrURL}}`
|
||||
// "space"
|
||||
: `{@${tag} ${namepathOrURL} ${text}}`;
|
||||
},
|
||||
|
||||
JsdocTag
|
||||
};
|
||||
|
||||
/**
|
||||
* @todo convert for use by escodegen (until may be patched to support
|
||||
* custom entries?).
|
||||
* @param {import('./commentParserToESTree').JsdocBlock|
|
||||
* import('./commentParserToESTree').JsdocDescriptionLine|
|
||||
* import('./commentParserToESTree').JsdocTypeLine|
|
||||
* import('./commentParserToESTree').JsdocTag|
|
||||
* import('./commentParserToESTree').JsdocInlineTag|
|
||||
* import('jsdoc-type-pratt-parser').RootResult
|
||||
* } node
|
||||
* @param {import('.').ESTreeToStringOptions} opts
|
||||
* @throws {Error}
|
||||
* @returns {string}
|
||||
*/
|
||||
function estreeToString (node, opts = {}) {
|
||||
if (Object.prototype.hasOwnProperty.call(stringifiers, node.type)) {
|
||||
return stringifiers[
|
||||
/**
|
||||
* @type {import('./commentParserToESTree').JsdocBlock|
|
||||
* import('./commentParserToESTree').JsdocDescriptionLine|
|
||||
* import('./commentParserToESTree').JsdocTypeLine|
|
||||
* import('./commentParserToESTree').JsdocTag}
|
||||
*/
|
||||
(node).type
|
||||
](
|
||||
node,
|
||||
opts
|
||||
);
|
||||
}
|
||||
|
||||
// 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
|
||||
? ''
|
||||
: `{${prattStringify(
|
||||
/** @type {import('jsdoc-type-pratt-parser').RootResult} */ (
|
||||
node
|
||||
)
|
||||
)}}`;
|
||||
}
|
||||
|
||||
throw new Error(`Unhandled node type: ${node.type}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {import('./commentParserToESTree').JsdocBlock} node
|
||||
* @param {import('.').ESTreeToStringOptions} opts
|
||||
* @returns {string}
|
||||
*/
|
||||
function JsdocBlock (node, opts) {
|
||||
const {delimiter, delimiterLineBreak, descriptionLines,
|
||||
initial, postDelimiter, preterminalLineBreak, tags, terminal} = node;
|
||||
|
||||
const terminalPrepend = preterminalLineBreak !== ''
|
||||
? `${preterminalLineBreak}${initial} `
|
||||
: '';
|
||||
|
||||
let result = `${initial}${delimiter}${postDelimiter}${delimiterLineBreak}`;
|
||||
|
||||
for (let i = 0; i < descriptionLines.length; i++) {
|
||||
result += estreeToString(descriptionLines[i]);
|
||||
|
||||
if (i !== descriptionLines.length - 1 || tags.length) {
|
||||
result += '\n';
|
||||
}
|
||||
}
|
||||
|
||||
for (let i = 0; i < tags.length; i++) {
|
||||
result += estreeToString(tags[i], opts);
|
||||
|
||||
if (i !== tags.length - 1) {
|
||||
result += '\n';
|
||||
}
|
||||
}
|
||||
|
||||
result += `${terminalPrepend}${terminal}`;
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {import('./commentParserToESTree').JsdocTag} node
|
||||
* @param {import('.').ESTreeToStringOptions} opts
|
||||
* @returns {string}
|
||||
*/
|
||||
function JsdocTag (node, opts) {
|
||||
const {
|
||||
delimiter, descriptionLines, initial, name, parsedType, postDelimiter,
|
||||
postName, postTag, postType, tag, typeLines
|
||||
} = node;
|
||||
|
||||
let result = `${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
|
||||
if (opts.preferRawType || !parsedType) {
|
||||
if (typeLines.length) {
|
||||
result += '{';
|
||||
|
||||
for (let i = 0; i < typeLines.length; i++) {
|
||||
result += estreeToString(typeLines[i]);
|
||||
|
||||
if (i !== typeLines.length - 1) {
|
||||
result += '\n';
|
||||
}
|
||||
}
|
||||
|
||||
result += '}';
|
||||
}
|
||||
} else if (parsedType?.type.startsWith('JsdocType')) {
|
||||
result += `{${prattStringify(
|
||||
/** @type {import('jsdoc-type-pratt-parser').RootResult} */ (
|
||||
parsedType
|
||||
)
|
||||
)}}`;
|
||||
}
|
||||
|
||||
result += name ? `${postType}${name}${postName}` : postType;
|
||||
|
||||
for (let i = 0; i < descriptionLines.length; i++) {
|
||||
const descriptionLine = descriptionLines[i];
|
||||
|
||||
result += estreeToString(descriptionLine);
|
||||
|
||||
if (i !== descriptionLines.length - 1) {
|
||||
result += '\n';
|
||||
}
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
export {estreeToString};
|
||||
50
node_modules/@es-joy/jsdoccomment/src/index.js
generated
vendored
Normal file
50
node_modules/@es-joy/jsdoccomment/src/index.js
generated
vendored
Normal file
@ -0,0 +1,50 @@
|
||||
/**
|
||||
* @typedef {import('./commentParserToESTree').JsdocInlineTagNoType & {
|
||||
* start: number,
|
||||
* end: number,
|
||||
* }} InlineTag
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {import('comment-parser').Spec & {
|
||||
* line?: import('./commentParserToESTree').Integer,
|
||||
* inlineTags: (import('./commentParserToESTree').JsdocInlineTagNoType & {
|
||||
* line?: import('./commentParserToESTree').Integer
|
||||
* })[]
|
||||
* }} JsdocTagWithInline
|
||||
*/
|
||||
|
||||
/**
|
||||
* Expands on comment-parser's `Block` interface.
|
||||
* @typedef {{
|
||||
* description: string,
|
||||
* source: import('comment-parser').Line[],
|
||||
* problems: import('comment-parser').Problem[],
|
||||
* tags: JsdocTagWithInline[],
|
||||
* inlineTags: (import('./commentParserToESTree').JsdocInlineTagNoType & {
|
||||
* line?: import('./commentParserToESTree').Integer
|
||||
* })[]
|
||||
* }} JsdocBlockWithInline
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {{preferRawType?: boolean}} ESTreeToStringOptions
|
||||
*/
|
||||
|
||||
/**
|
||||
* @callback CommentHandler
|
||||
* @param {string} commentSelector
|
||||
* @param {import('.').JsdocBlockWithInline} jsdoc
|
||||
* @returns {boolean}
|
||||
*/
|
||||
|
||||
export {visitorKeys as jsdocTypeVisitorKeys} from 'jsdoc-type-pratt-parser';
|
||||
|
||||
export * from 'jsdoc-type-pratt-parser';
|
||||
|
||||
export * from './commentHandler.js';
|
||||
export * from './commentParserToESTree.js';
|
||||
export * from './estreeToString.js';
|
||||
export * from './jsdoccomment.js';
|
||||
export * from './parseComment.js';
|
||||
export * from './parseInlineTags.js';
|
||||
487
node_modules/@es-joy/jsdoccomment/src/jsdoccomment.js
generated
vendored
Normal file
487
node_modules/@es-joy/jsdoccomment/src/jsdoccomment.js
generated
vendored
Normal file
@ -0,0 +1,487 @@
|
||||
/**
|
||||
* Obtained originally from {@link https://github.com/eslint/eslint/blob/master/lib/util/source-code.js#L313}.
|
||||
*
|
||||
* @license MIT
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {import('eslint').AST.Token | import('estree').Comment | {
|
||||
* type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
|
||||
* range: [number, number],
|
||||
* value: string
|
||||
* }} Token
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {import('eslint').Rule.Node|
|
||||
* import('@typescript-eslint/types').TSESTree.Node} ESLintOrTSNode
|
||||
*/
|
||||
|
||||
/**
|
||||
* @typedef {number} int
|
||||
*/
|
||||
|
||||
/**
|
||||
* Checks if the given token is a comment token or not.
|
||||
*
|
||||
* @param {Token} token - The token to check.
|
||||
* @returns {boolean} `true` if the token is a comment token.
|
||||
*/
|
||||
const isCommentToken = (token) => {
|
||||
return token.type === 'Line' || token.type === 'Block' ||
|
||||
token.type === 'Shebang';
|
||||
};
|
||||
|
||||
/**
|
||||
* @param {(ESLintOrTSNode|import('estree').Comment) & {
|
||||
* declaration?: any,
|
||||
* decorators?: any[],
|
||||
* parent?: import('eslint').Rule.Node & {
|
||||
* decorators?: any[]
|
||||
* }
|
||||
* }} node
|
||||
* @returns {import('@typescript-eslint/types').TSESTree.Decorator|undefined}
|
||||
*/
|
||||
const getDecorator = (node) => {
|
||||
return node?.declaration?.decorators?.[0] || node?.decorators?.[0] ||
|
||||
node?.parent?.decorators?.[0];
|
||||
};
|
||||
|
||||
/**
|
||||
* Check to see if it is a ES6 export declaration.
|
||||
*
|
||||
* @param {ESLintOrTSNode} astNode An AST node.
|
||||
* @returns {boolean} whether the given node represents an export declaration.
|
||||
* @private
|
||||
*/
|
||||
const looksLikeExport = function (astNode) {
|
||||
return astNode.type === 'ExportDefaultDeclaration' ||
|
||||
astNode.type === 'ExportNamedDeclaration' ||
|
||||
astNode.type === 'ExportAllDeclaration' ||
|
||||
astNode.type === 'ExportSpecifier';
|
||||
};
|
||||
|
||||
/**
|
||||
* @param {ESLintOrTSNode} astNode
|
||||
* @returns {ESLintOrTSNode}
|
||||
*/
|
||||
const getTSFunctionComment = function (astNode) {
|
||||
const {parent} = astNode;
|
||||
/* v8 ignore next 3 */
|
||||
if (!parent) {
|
||||
return astNode;
|
||||
}
|
||||
const grandparent = parent.parent;
|
||||
/* v8 ignore next 3 */
|
||||
if (!grandparent) {
|
||||
return astNode;
|
||||
}
|
||||
const greatGrandparent = grandparent.parent;
|
||||
const greatGreatGrandparent = greatGrandparent && greatGrandparent.parent;
|
||||
|
||||
/* v8 ignore next 3 */
|
||||
if (/** @type {ESLintOrTSNode} */ (parent).type !== 'TSTypeAnnotation') {
|
||||
return astNode;
|
||||
}
|
||||
|
||||
switch (/** @type {ESLintOrTSNode} */ (grandparent).type) {
|
||||
// @ts-expect-error -- For `ClassProperty`.
|
||||
case 'PropertyDefinition': case 'ClassProperty':
|
||||
case 'TSDeclareFunction':
|
||||
case 'TSMethodSignature':
|
||||
case 'TSPropertySignature':
|
||||
return grandparent;
|
||||
case 'ArrowFunctionExpression':
|
||||
/* v8 ignore next 3 */
|
||||
if (!greatGrandparent) {
|
||||
return astNode;
|
||||
}
|
||||
|
||||
if (
|
||||
greatGrandparent.type === 'VariableDeclarator'
|
||||
|
||||
// && greatGreatGrandparent.parent.type === 'VariableDeclaration'
|
||||
) {
|
||||
/* v8 ignore next 3 */
|
||||
if (!greatGreatGrandparent || !greatGreatGrandparent.parent) {
|
||||
return astNode;
|
||||
}
|
||||
return greatGreatGrandparent.parent;
|
||||
}
|
||||
/* v8 ignore next */
|
||||
return astNode;
|
||||
case 'FunctionExpression':
|
||||
/* v8 ignore next 3 */
|
||||
if (!greatGreatGrandparent) {
|
||||
return astNode;
|
||||
}
|
||||
if (greatGrandparent.type === 'MethodDefinition') {
|
||||
return greatGrandparent;
|
||||
}
|
||||
|
||||
// Fallthrough
|
||||
default:
|
||||
/* v8 ignore next 3 */
|
||||
if (grandparent.type !== 'Identifier') {
|
||||
return astNode;
|
||||
}
|
||||
}
|
||||
|
||||
/* v8 ignore next 3 */
|
||||
if (!greatGreatGrandparent) {
|
||||
return astNode;
|
||||
}
|
||||
|
||||
switch (greatGrandparent.type) {
|
||||
case 'ArrowFunctionExpression':
|
||||
if (
|
||||
greatGreatGrandparent.type === 'VariableDeclarator' &&
|
||||
greatGreatGrandparent.parent.type === 'VariableDeclaration'
|
||||
) {
|
||||
return greatGreatGrandparent.parent;
|
||||
}
|
||||
|
||||
return astNode;
|
||||
case 'FunctionDeclaration':
|
||||
return greatGrandparent;
|
||||
case 'VariableDeclarator':
|
||||
if (greatGreatGrandparent.type === 'VariableDeclaration') {
|
||||
return greatGreatGrandparent;
|
||||
}
|
||||
/* v8 ignore next 2 */
|
||||
// Fallthrough
|
||||
default:
|
||||
/* v8 ignore next 3 */
|
||||
return astNode;
|
||||
}
|
||||
};
|
||||
|
||||
const invokedExpression = new Set(
|
||||
['CallExpression', 'OptionalCallExpression', 'NewExpression']
|
||||
);
|
||||
const allowableCommentNode = new Set([
|
||||
'AssignmentPattern',
|
||||
'VariableDeclaration',
|
||||
'ExpressionStatement',
|
||||
'MethodDefinition',
|
||||
'Property',
|
||||
'ObjectProperty',
|
||||
'ClassProperty',
|
||||
'PropertyDefinition',
|
||||
'ExportDefaultDeclaration',
|
||||
'ReturnStatement'
|
||||
]);
|
||||
|
||||
/**
|
||||
* Reduces the provided node to the appropriate node for evaluating
|
||||
* JSDoc comment status.
|
||||
*
|
||||
* @param {ESLintOrTSNode} node An AST node.
|
||||
* @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode.
|
||||
* @returns {ESLintOrTSNode} The AST node that
|
||||
* can be evaluated for appropriate JSDoc comments.
|
||||
*/
|
||||
const getReducedASTNode = function (node, sourceCode) {
|
||||
let {parent} = node;
|
||||
|
||||
switch (/** @type {ESLintOrTSNode} */ (node).type) {
|
||||
case 'TSFunctionType':
|
||||
return getTSFunctionComment(node);
|
||||
case 'TSInterfaceDeclaration':
|
||||
case 'TSTypeAliasDeclaration':
|
||||
case 'TSEnumDeclaration':
|
||||
case 'ClassDeclaration':
|
||||
case 'FunctionDeclaration':
|
||||
/* v8 ignore next 3 */
|
||||
if (!parent) {
|
||||
return node;
|
||||
}
|
||||
return looksLikeExport(parent) ? parent : node;
|
||||
|
||||
case 'TSDeclareFunction':
|
||||
case 'ClassExpression':
|
||||
case 'ObjectExpression':
|
||||
case 'ArrowFunctionExpression':
|
||||
case 'TSEmptyBodyFunctionExpression':
|
||||
case 'FunctionExpression':
|
||||
/* v8 ignore next 3 */
|
||||
if (!parent) {
|
||||
return node;
|
||||
}
|
||||
if (
|
||||
!invokedExpression.has(parent.type)
|
||||
) {
|
||||
/**
|
||||
* @type {ESLintOrTSNode|Token|null}
|
||||
*/
|
||||
let token = node;
|
||||
do {
|
||||
token = sourceCode.getTokenBefore(
|
||||
/** @type {import('eslint').Rule.Node|import('eslint').AST.Token} */ (
|
||||
token
|
||||
),
|
||||
{includeComments: true}
|
||||
);
|
||||
} while (token && token.type === 'Punctuator' && token.value === '(');
|
||||
if (token && token.type === 'Block') {
|
||||
return node;
|
||||
}
|
||||
|
||||
if (sourceCode.getCommentsBefore(
|
||||
/** @type {import('eslint').Rule.Node} */
|
||||
(node)
|
||||
).length) {
|
||||
return node;
|
||||
}
|
||||
|
||||
while (
|
||||
!sourceCode.getCommentsBefore(
|
||||
/** @type {import('eslint').Rule.Node} */
|
||||
(parent)
|
||||
).length &&
|
||||
!(/Function/u).test(parent.type) &&
|
||||
!allowableCommentNode.has(parent.type)
|
||||
) {
|
||||
({parent} = parent);
|
||||
|
||||
if (!parent) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (parent && parent.type !== 'FunctionDeclaration' &&
|
||||
parent.type !== 'Program'
|
||||
) {
|
||||
if (parent.parent && parent.parent.type === 'ExportNamedDeclaration') {
|
||||
return parent.parent;
|
||||
}
|
||||
|
||||
return parent;
|
||||
}
|
||||
}
|
||||
|
||||
return node;
|
||||
|
||||
default:
|
||||
return node;
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Checks for the presence of a JSDoc comment for the given node and returns it.
|
||||
*
|
||||
* @param {ESLintOrTSNode} astNode The AST node to get
|
||||
* the comment for.
|
||||
* @param {import('eslint').SourceCode} sourceCode
|
||||
* @param {{maxLines: int, minLines: int, [name: string]: any}} settings
|
||||
* @param {{nonJSDoc?: boolean}} [opts]
|
||||
* @returns {Token|null} The Block comment token containing the JSDoc comment
|
||||
* for the given node or null if not found.
|
||||
*/
|
||||
const findJSDocComment = (astNode, sourceCode, settings, opts = {}) => {
|
||||
const {nonJSDoc} = opts;
|
||||
const {minLines, maxLines} = settings;
|
||||
|
||||
/** @type {ESLintOrTSNode|import('estree').Comment} */
|
||||
let currentNode = astNode;
|
||||
let tokenBefore = null;
|
||||
let parenthesisToken = null;
|
||||
|
||||
while (currentNode) {
|
||||
const decorator = getDecorator(
|
||||
/** @type {import('eslint').Rule.Node} */
|
||||
(currentNode)
|
||||
);
|
||||
if (decorator) {
|
||||
const dec = /** @type {unknown} */ (decorator);
|
||||
currentNode = /** @type {import('eslint').Rule.Node} */ (dec);
|
||||
}
|
||||
tokenBefore = sourceCode.getTokenBefore(
|
||||
/** @type {import('eslint').Rule.Node} */
|
||||
(currentNode),
|
||||
{includeComments: true}
|
||||
);
|
||||
if (
|
||||
tokenBefore && tokenBefore.type === 'Punctuator' &&
|
||||
tokenBefore.value === '('
|
||||
) {
|
||||
parenthesisToken = tokenBefore;
|
||||
[tokenBefore] = sourceCode.getTokensBefore(
|
||||
/** @type {import('eslint').Rule.Node} */
|
||||
(currentNode),
|
||||
{
|
||||
count: 2,
|
||||
includeComments: true
|
||||
}
|
||||
);
|
||||
}
|
||||
if (!tokenBefore || !isCommentToken(tokenBefore)) {
|
||||
return null;
|
||||
}
|
||||
if (!nonJSDoc && tokenBefore.type === 'Line') {
|
||||
currentNode = tokenBefore;
|
||||
continue;
|
||||
}
|
||||
break;
|
||||
}
|
||||
|
||||
/* v8 ignore next 3 */
|
||||
if (!tokenBefore || !currentNode.loc || !tokenBefore.loc) {
|
||||
return null;
|
||||
}
|
||||
|
||||
if (
|
||||
(
|
||||
(nonJSDoc && (tokenBefore.type !== 'Block' ||
|
||||
!(/^\*\s/u).test(tokenBefore.value))) ||
|
||||
(!nonJSDoc && tokenBefore.type === 'Block' &&
|
||||
(/^\*\s/u).test(tokenBefore.value))
|
||||
) &&
|
||||
currentNode.loc.start.line - (
|
||||
/** @type {import('eslint').AST.Token} */
|
||||
(parenthesisToken ?? tokenBefore)
|
||||
).loc.end.line >= minLines &&
|
||||
currentNode.loc.start.line - (
|
||||
/** @type {import('eslint').AST.Token} */
|
||||
(parenthesisToken ?? tokenBefore)
|
||||
).loc.end.line <= maxLines
|
||||
) {
|
||||
return tokenBefore;
|
||||
}
|
||||
|
||||
return null;
|
||||
};
|
||||
|
||||
/**
|
||||
* Retrieves the JSDoc comment for a given node.
|
||||
*
|
||||
* @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode
|
||||
* @param {import('eslint').Rule.Node} node The AST node to get
|
||||
* the comment for.
|
||||
* @param {{maxLines: int, minLines: int, [name: string]: any}} settings The
|
||||
* settings in context
|
||||
* @returns {Token|null} The Block comment
|
||||
* token containing the JSDoc comment for the given node or
|
||||
* null if not found.
|
||||
* @public
|
||||
*/
|
||||
const getJSDocComment = function (sourceCode, node, settings) {
|
||||
const reducedNode = getReducedASTNode(node, sourceCode);
|
||||
|
||||
return findJSDocComment(reducedNode, sourceCode, settings);
|
||||
};
|
||||
|
||||
/**
|
||||
* Retrieves the comment preceding a given node.
|
||||
*
|
||||
* @param {import('eslint').SourceCode} sourceCode The ESLint SourceCode
|
||||
* @param {ESLintOrTSNode} node The AST node to get
|
||||
* the comment for.
|
||||
* @param {{maxLines: int, minLines: int, [name: string]: any}} settings The
|
||||
* settings in context
|
||||
* @returns {Token|null} The Block comment
|
||||
* token containing the JSDoc comment for the given node or
|
||||
* null if not found.
|
||||
* @public
|
||||
*/
|
||||
const getNonJsdocComment = function (sourceCode, node, settings) {
|
||||
const reducedNode = getReducedASTNode(node, sourceCode);
|
||||
|
||||
return findJSDocComment(reducedNode, sourceCode, settings, {
|
||||
nonJSDoc: true
|
||||
});
|
||||
};
|
||||
|
||||
/**
|
||||
* @param {ESLintOrTSNode|import('eslint').AST.Token|
|
||||
* import('estree').Comment
|
||||
* } nodeA The AST node or token to compare
|
||||
* @param {ESLintOrTSNode|import('eslint').AST.Token|
|
||||
* import('estree').Comment} nodeB The
|
||||
* AST node or token to compare
|
||||
*/
|
||||
const compareLocEndToStart = (nodeA, nodeB) => {
|
||||
/* v8 ignore next */
|
||||
return (nodeA.loc?.end.line ?? 0) === (nodeB.loc?.start.line ?? 0);
|
||||
};
|
||||
|
||||
/**
|
||||
* Checks for the presence of a comment following the given node and
|
||||
* returns it.
|
||||
*
|
||||
* This method is experimental.
|
||||
*
|
||||
* @param {import('eslint').SourceCode} sourceCode
|
||||
* @param {ESLintOrTSNode} astNode The AST node to get
|
||||
* the comment for.
|
||||
* @returns {Token|null} The comment token containing the comment
|
||||
* for the given node or null if not found.
|
||||
*/
|
||||
const getFollowingComment = function (sourceCode, astNode) {
|
||||
/**
|
||||
* @param {ESLintOrTSNode} node The
|
||||
* AST node to get the comment for.
|
||||
*/
|
||||
const getTokensAfterIgnoringSemis = (node) => {
|
||||
let tokenAfter = sourceCode.getTokenAfter(
|
||||
/** @type {import('eslint').Rule.Node} */
|
||||
(node),
|
||||
{includeComments: true}
|
||||
);
|
||||
|
||||
while (
|
||||
tokenAfter && tokenAfter.type === 'Punctuator' &&
|
||||
// tokenAfter.value === ')' // Don't apparently need to ignore
|
||||
tokenAfter.value === ';'
|
||||
) {
|
||||
[tokenAfter] = sourceCode.getTokensAfter(tokenAfter, {
|
||||
includeComments: true
|
||||
});
|
||||
}
|
||||
return tokenAfter;
|
||||
};
|
||||
|
||||
/**
|
||||
* @param {ESLintOrTSNode} node The
|
||||
* AST node to get the comment for.
|
||||
*/
|
||||
const tokenAfterIgnoringSemis = (node) => {
|
||||
const tokenAfter = getTokensAfterIgnoringSemis(node);
|
||||
return (
|
||||
tokenAfter &&
|
||||
isCommentToken(tokenAfter) &&
|
||||
compareLocEndToStart(node, tokenAfter)
|
||||
)
|
||||
? tokenAfter
|
||||
: null;
|
||||
};
|
||||
|
||||
let tokenAfter = tokenAfterIgnoringSemis(astNode);
|
||||
|
||||
if (!tokenAfter) {
|
||||
switch (astNode.type) {
|
||||
case 'FunctionDeclaration':
|
||||
tokenAfter = tokenAfterIgnoringSemis(
|
||||
/** @type {ESLintOrTSNode} */
|
||||
(astNode.body)
|
||||
);
|
||||
break;
|
||||
case 'ExpressionStatement':
|
||||
tokenAfter = tokenAfterIgnoringSemis(
|
||||
/** @type {ESLintOrTSNode} */
|
||||
(astNode.expression)
|
||||
);
|
||||
break;
|
||||
|
||||
/* v8 ignore next 3 */
|
||||
default:
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
return tokenAfter;
|
||||
};
|
||||
|
||||
export {
|
||||
getReducedASTNode, getJSDocComment, getNonJsdocComment,
|
||||
getDecorator, findJSDocComment, getFollowingComment
|
||||
};
|
||||
190
node_modules/@es-joy/jsdoccomment/src/parseComment.js
generated
vendored
Normal file
190
node_modules/@es-joy/jsdoccomment/src/parseComment.js
generated
vendored
Normal file
@ -0,0 +1,190 @@
|
||||
/* eslint-disable prefer-named-capture-group -- Temporary */
|
||||
import {
|
||||
parse as commentParser,
|
||||
tokenizers
|
||||
} from 'comment-parser';
|
||||
|
||||
import {parseInlineTags} from './parseInlineTags.js';
|
||||
|
||||
const {
|
||||
name: nameTokenizer,
|
||||
tag: tagTokenizer,
|
||||
type: typeTokenizer,
|
||||
description: descriptionTokenizer
|
||||
} = tokenizers;
|
||||
|
||||
/**
|
||||
* @param {import('comment-parser').Spec} spec
|
||||
* @returns {boolean}
|
||||
*/
|
||||
export const hasSeeWithLink = (spec) => {
|
||||
return spec.tag === 'see' && (/\{@link.+?\}/u).test(spec.source[0].source);
|
||||
};
|
||||
|
||||
export const defaultNoTypes = [
|
||||
'default', 'defaultvalue', 'description', 'example',
|
||||
'file', 'fileoverview', 'license',
|
||||
'overview', 'see', 'summary'
|
||||
];
|
||||
|
||||
export const defaultNoNames = [
|
||||
'access', 'author',
|
||||
'default', 'defaultvalue',
|
||||
'description',
|
||||
'example', 'exception', 'file', 'fileoverview',
|
||||
'kind',
|
||||
'license', 'overview',
|
||||
'return', 'returns',
|
||||
'since', 'summary',
|
||||
'throws',
|
||||
'version', 'variation'
|
||||
];
|
||||
|
||||
const optionalBrackets = /^\[(?<name>[^=]*)=[^\]]*\]/u;
|
||||
const preserveTypeTokenizer = typeTokenizer('preserve');
|
||||
const preserveDescriptionTokenizer = descriptionTokenizer('preserve');
|
||||
const plainNameTokenizer = nameTokenizer();
|
||||
|
||||
/**
|
||||
* Can't import `comment-parser/es6/parser/tokenizers/index.js`,
|
||||
* so we redefine here.
|
||||
* @typedef {(spec: import('comment-parser').Spec) =>
|
||||
* import('comment-parser').Spec} CommentParserTokenizer
|
||||
*/
|
||||
|
||||
/**
|
||||
* @param {object} [cfg]
|
||||
* @param {string[]} [cfg.noTypes]
|
||||
* @param {string[]} [cfg.noNames]
|
||||
* @returns {CommentParserTokenizer[]}
|
||||
*/
|
||||
const getTokenizers = ({
|
||||
noTypes = defaultNoTypes,
|
||||
noNames = defaultNoNames
|
||||
} = {}) => {
|
||||
// trim
|
||||
return [
|
||||
// Tag
|
||||
tagTokenizer(),
|
||||
|
||||
/**
|
||||
* Type tokenizer.
|
||||
* @param {import('comment-parser').Spec} spec
|
||||
* @returns {import('comment-parser').Spec}
|
||||
*/
|
||||
(spec) => {
|
||||
if (noTypes.includes(spec.tag)) {
|
||||
return spec;
|
||||
}
|
||||
|
||||
return preserveTypeTokenizer(spec);
|
||||
},
|
||||
|
||||
/**
|
||||
* Name tokenizer.
|
||||
* @param {import('comment-parser').Spec} spec
|
||||
* @returns {import('comment-parser').Spec}
|
||||
*/
|
||||
(spec) => {
|
||||
if (spec.tag === 'template') {
|
||||
// const preWS = spec.postTag;
|
||||
const remainder = spec.source[0].tokens.description;
|
||||
|
||||
let pos;
|
||||
if (remainder.startsWith('[') && remainder.includes(']')) {
|
||||
const endingBracketPos = remainder.indexOf(']');
|
||||
pos = remainder.slice(endingBracketPos).search(/(?<![\s,])\s/u);
|
||||
if (pos > -1) { // Add offset to starting point if space found
|
||||
pos += endingBracketPos;
|
||||
}
|
||||
} else {
|
||||
pos = remainder.search(/(?<![\s,])\s/u);
|
||||
}
|
||||
|
||||
let name = pos === -1 ? remainder : remainder.slice(0, pos);
|
||||
const extra = remainder.slice(pos);
|
||||
let postName = '', description = '', lineEnd = '';
|
||||
if (pos > -1) {
|
||||
[, postName, description, lineEnd] = /** @type {RegExpMatchArray} */ (
|
||||
extra.match(/(\s*)([^\r]*)(\r)?/u)
|
||||
);
|
||||
}
|
||||
|
||||
if (optionalBrackets.test(name)) {
|
||||
name = /** @type {string} */ (
|
||||
/** @type {RegExpMatchArray} */ (
|
||||
name.match(optionalBrackets)
|
||||
)?.groups?.name
|
||||
);
|
||||
spec.optional = true;
|
||||
} else {
|
||||
spec.optional = false;
|
||||
}
|
||||
|
||||
spec.name = name;
|
||||
const {tokens} = spec.source[0];
|
||||
tokens.name = name;
|
||||
tokens.postName = postName;
|
||||
tokens.description = description;
|
||||
tokens.lineEnd = lineEnd || '';
|
||||
|
||||
return spec;
|
||||
}
|
||||
|
||||
if (noNames.includes(spec.tag) || hasSeeWithLink(spec)) {
|
||||
return spec;
|
||||
}
|
||||
|
||||
return plainNameTokenizer(spec);
|
||||
},
|
||||
|
||||
/**
|
||||
* Description tokenizer.
|
||||
* @param {import('comment-parser').Spec} spec
|
||||
* @returns {import('comment-parser').Spec}
|
||||
*/
|
||||
(spec) => {
|
||||
return preserveDescriptionTokenizer(spec);
|
||||
}
|
||||
];
|
||||
};
|
||||
|
||||
/**
|
||||
* Accepts a comment token or complete comment string and converts it into
|
||||
* `comment-parser` AST.
|
||||
* @param {string | {value: string}} commentOrNode
|
||||
* @param {string} [indent] Whitespace
|
||||
* @returns {import('.').JsdocBlockWithInline}
|
||||
*/
|
||||
const parseComment = (commentOrNode, indent = '') => {
|
||||
let block;
|
||||
|
||||
switch (typeof commentOrNode) {
|
||||
case 'string':
|
||||
// Preserve JSDoc block start/end indentation.
|
||||
[block] = commentParser(`${indent}${commentOrNode}`, {
|
||||
// @see https://github.com/yavorskiy/comment-parser/issues/21
|
||||
tokenizers: getTokenizers()
|
||||
});
|
||||
break;
|
||||
|
||||
case 'object':
|
||||
if (commentOrNode === null) {
|
||||
throw new TypeError(`'commentOrNode' is not a string or object.`);
|
||||
}
|
||||
|
||||
// Preserve JSDoc block start/end indentation.
|
||||
[block] = commentParser(`${indent}/*${commentOrNode.value}*/`, {
|
||||
// @see https://github.com/yavorskiy/comment-parser/issues/21
|
||||
tokenizers: getTokenizers()
|
||||
});
|
||||
break;
|
||||
|
||||
default:
|
||||
throw new TypeError(`'commentOrNode' is not a string or object.`);
|
||||
}
|
||||
|
||||
return parseInlineTags(block);
|
||||
};
|
||||
|
||||
export {getTokenizers, parseComment};
|
||||
108
node_modules/@es-joy/jsdoccomment/src/parseInlineTags.js
generated
vendored
Normal file
108
node_modules/@es-joy/jsdoccomment/src/parseInlineTags.js
generated
vendored
Normal file
@ -0,0 +1,108 @@
|
||||
/**
|
||||
* @param {RegExpMatchArray & {
|
||||
* indices: {
|
||||
* groups: {
|
||||
* [key: string]: [number, number]
|
||||
* }
|
||||
* }
|
||||
* groups: {[key: string]: string}
|
||||
* }} match An inline tag regexp match.
|
||||
* @returns {'pipe' | 'plain' | 'prefix' | 'space'}
|
||||
*/
|
||||
function determineFormat (match) {
|
||||
const {separator, text} = match.groups;
|
||||
const [, textEnd] = match.indices.groups.text;
|
||||
const [tagStart] = match.indices.groups.tag;
|
||||
if (!text) {
|
||||
return 'plain';
|
||||
} else if (separator === '|') {
|
||||
return 'pipe';
|
||||
} else if (textEnd < tagStart) {
|
||||
return 'prefix';
|
||||
}
|
||||
return 'space';
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracts inline tags from a description.
|
||||
* @param {string} description
|
||||
* @returns {import('.').InlineTag[]} Array of inline tags from the description.
|
||||
*/
|
||||
function parseDescription (description) {
|
||||
/** @type {import('.').InlineTag[]} */
|
||||
const result = [];
|
||||
|
||||
// This could have been expressed in a single pattern,
|
||||
// but having two avoids a potentially exponential time regex.
|
||||
|
||||
const prefixedTextPattern = new RegExp(/(?:\[(?<text>[^\]]+)\])\{@(?<tag>[^}\s]+)\s?(?<namepathOrURL>[^}\s|]*)\}/gu, 'gud');
|
||||
// The pattern used to match for text after tag uses a negative lookbehind
|
||||
// on the ']' char to avoid matching the prefixed case too.
|
||||
const suffixedAfterPattern = new RegExp(/(?<!\])\{@(?<tag>[^}\s]+)\s?(?<namepathOrURL>[^}\s|]*)\s*(?<separator>[\s|])?\s*(?<text>[^}]*)\}/gu, 'gud');
|
||||
|
||||
const matches = [
|
||||
...description.matchAll(prefixedTextPattern),
|
||||
...description.matchAll(suffixedAfterPattern)
|
||||
];
|
||||
|
||||
for (const mtch of matches) {
|
||||
const match = /**
|
||||
* @type {RegExpMatchArray & {
|
||||
* indices: {
|
||||
* groups: {
|
||||
* [key: string]: [number, number]
|
||||
* }
|
||||
* }
|
||||
* groups: {[key: string]: string}
|
||||
* }}
|
||||
*/ (
|
||||
mtch
|
||||
);
|
||||
const {tag, namepathOrURL, text} = match.groups;
|
||||
const [start, end] = match.indices[0];
|
||||
const format = determineFormat(match);
|
||||
|
||||
result.push({
|
||||
tag,
|
||||
namepathOrURL,
|
||||
text,
|
||||
format,
|
||||
start,
|
||||
end
|
||||
});
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Splits the `{@prefix}` from remaining `Spec.lines[].token.description`
|
||||
* into the `inlineTags` tokens, and populates `spec.inlineTags`
|
||||
* @param {import('comment-parser').Block} block
|
||||
* @returns {import('.').JsdocBlockWithInline}
|
||||
*/
|
||||
export function parseInlineTags (block) {
|
||||
const inlineTags =
|
||||
/**
|
||||
* @type {(import('./commentParserToESTree').JsdocInlineTagNoType & {
|
||||
* line?: import('./commentParserToESTree').Integer
|
||||
* })[]}
|
||||
*/ (
|
||||
parseDescription(block.description)
|
||||
);
|
||||
|
||||
/** @type {import('.').JsdocBlockWithInline} */ (
|
||||
block
|
||||
).inlineTags = inlineTags;
|
||||
|
||||
for (const tag of block.tags) {
|
||||
/**
|
||||
* @type {import('.').JsdocTagWithInline}
|
||||
*/ (tag).inlineTags = parseDescription(tag.description);
|
||||
}
|
||||
return (
|
||||
/**
|
||||
* @type {import('.').JsdocBlockWithInline}
|
||||
*/ (block)
|
||||
);
|
||||
}
|
||||
13
node_modules/@es-joy/jsdoccomment/src/toCamelCase.js
generated
vendored
Normal file
13
node_modules/@es-joy/jsdoccomment/src/toCamelCase.js
generated
vendored
Normal file
@ -0,0 +1,13 @@
|
||||
/**
|
||||
* @param {string} str
|
||||
* @returns {string}
|
||||
*/
|
||||
const toCamelCase = (str) => {
|
||||
return str.toLowerCase().replaceAll(/^[a-z]/gu, (init) => {
|
||||
return init.toUpperCase();
|
||||
}).replaceAll(/_(?<wordInit>[a-z])/gu, (_, n1, o, s, {wordInit}) => {
|
||||
return wordInit.toUpperCase();
|
||||
});
|
||||
};
|
||||
|
||||
export {toCamelCase};
|
||||
Reference in New Issue
Block a user