├── .babelrc.json ├── .editorconfig ├── .gitattributes ├── .github └── workflows │ └── ci.yml ├── .gitignore ├── .ncurc.cjs ├── CHANGES.md ├── LICENSE-MIT.txt ├── README.md ├── dist ├── index.cjs.cjs ├── index.d.cts └── index.d.ts ├── docs ├── .nojekyll ├── assets │ ├── dmt │ │ ├── dmt-component-data.js │ │ ├── dmt-components.css │ │ ├── dmt-components.js │ │ ├── dmt-search.cmp │ │ ├── dmt-theme.css │ │ └── icons │ │ │ └── service │ │ │ ├── github.png │ │ │ └── npm.png │ ├── highlight.css │ ├── icons.js │ ├── icons.svg │ ├── main.js │ └── style.css ├── functions │ ├── catharsisTransform.html │ ├── commentHandler.html │ ├── commentParserToESTree.html │ ├── estreeToString.html │ ├── findJSDocComment.html │ ├── getDecorator.html │ ├── getFollowingComment.html │ ├── getJSDocComment.html │ ├── getNonJsdocComment.html │ ├── getReducedASTNode.html │ ├── getTokenizers.html │ ├── hasSeeWithLink.html │ ├── identityTransformRules.html │ ├── jtpTransform.html │ ├── parse.html │ ├── parseComment.html │ ├── parseInlineTags.html │ ├── stringify.html │ ├── stringifyRules.html │ ├── transform.html │ ├── traverse.html │ └── tryParse.html ├── index.html ├── interfaces │ ├── AnyResult.html │ ├── AssertsResult.html │ ├── FunctionResult.html │ ├── GenericResult.html │ ├── ImportResult.html │ ├── IndexSignatureResult.html │ ├── IntersectionResult.html │ ├── JsdocObjectFieldResult.html │ ├── KeyOfResult.html │ ├── KeyValueResult.html │ ├── MappedTypeResult.html │ ├── NamePathResult.html │ ├── NameResult.html │ ├── NotNullableResult.html │ ├── NullResult.html │ ├── NullableResult.html │ ├── NumberResult.html │ ├── ObjectFieldResult.html │ ├── ObjectResult.html │ ├── OptionalResult.html │ ├── ParenthesisResult.html │ ├── PredicateResult.html │ ├── PropertyResult.html │ ├── SpecialNamePath.html │ ├── StringValueResult.html │ ├── SymbolResult.html │ ├── TupleResult.html │ ├── TypeOfResult.html │ ├── UndefinedResult.html │ ├── UnionResult.html │ ├── UnknownResult.html │ └── VariadicResult.html ├── modules.html ├── modules │ └── jsdocVisitorKeys.html ├── types │ ├── CommentHandler-1.html │ ├── CommentParserTokenizer.html │ ├── ESLintOrTSNode.html │ ├── ESTreeToStringOptions.html │ ├── InlineTag.html │ ├── Integer.html │ ├── JsdocBlock.html │ ├── JsdocBlockWithInline.html │ ├── JsdocDescriptionLine.html │ ├── JsdocInlineTag.html │ ├── JsdocInlineTagNoType.html │ ├── JsdocTag.html │ ├── JsdocTagWithInline.html │ ├── JsdocTypeLine.html │ ├── NodeVisitor.html │ ├── NonRootResult.html │ ├── ParseMode.html │ ├── QuoteStyle.html │ ├── RootResult.html │ ├── SpecialNamePathType.html │ ├── Token.html │ ├── TransformFunction.html │ ├── TransformRule.html │ ├── TransformRules.html │ ├── VisitorKeys.html │ └── int.html └── variables │ ├── defaultNoNames.html │ ├── defaultNoTypes.html │ ├── jsdocTypeVisitorKeys.html │ ├── jsdocVisitorKeys.JsdocBlock.html │ ├── jsdocVisitorKeys.JsdocDescriptionLine.html │ ├── jsdocVisitorKeys.JsdocInlineTag.html │ ├── jsdocVisitorKeys.JsdocTag.html │ └── jsdocVisitorKeys.JsdocTypeLine.html ├── eslint.config.js ├── package.json ├── pnpm-lock.yaml ├── rollup.config.js ├── src ├── commentHandler.js ├── commentParserToESTree.js ├── estreeToString.js ├── index.js ├── jsdoccomment.js ├── parseComment.js ├── parseInlineTags.js └── toCamelCase.js ├── test ├── commentHandler.test.js ├── commentParserToESTree.test.js ├── estreeToString.test.js ├── fixture │ └── roundTripData.js ├── getJSDocComment.test.js ├── jsdoccomment.test.js ├── parseComment.test.js ├── roundTripParsing.test.js └── toCamelCase.test.js ├── tsconfig.json ├── typings └── espree.d.ts └── vitest.config.js /.babelrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "plugins": [ 3 | "@babel/plugin-syntax-class-properties" 4 | ], 5 | "presets": [ 6 | [ 7 | "@babel/preset-env", 8 | { 9 | "targets": { 10 | "node": 18 11 | } 12 | } 13 | ] 14 | ], 15 | "env": { 16 | "test": { 17 | "plugins": [ "istanbul" ] 18 | } 19 | } 20 | } 21 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | ; EditorConfig file: https://EditorConfig.org 2 | ; Install the "EditorConfig" plugin into your editor to use 3 | 4 | root = true 5 | 6 | [*] 7 | charset = utf-8 8 | end_of_line = lf 9 | insert_final_newline = true 10 | indent_style = space 11 | indent_size = 2 12 | trim_trailing_whitespace = true 13 | 14 | [*.md] 15 | indent_size = 4 16 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Set line endings / allows Windows checkout to pass Eslint rules. 2 | * text eol=lf 3 | 4 | # Denote all files that are truly binary and should not be modified. 5 | *.png binary 6 | *.jpg binary 7 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI/CD 2 | 3 | on: 4 | push: 5 | branches: [ main ] 6 | pull_request: 7 | branches: [ main ] 8 | 9 | jobs: 10 | build-node: 11 | strategy: 12 | fail-fast: false 13 | matrix: 14 | os: [ubuntu-latest, windows-latest, macos-latest] 15 | node-version: [18.x, 20.x, 22.x] 16 | 17 | runs-on: ${{ matrix.os }} 18 | 19 | steps: 20 | - name: Checkout repository 21 | uses: actions/checkout@v3 22 | 23 | - name: Set up Node.js ${{ matrix.node-version }} 24 | uses: actions/setup-node@v3 25 | with: 26 | node-version: ${{ matrix.node-version }} 27 | 28 | - name: Install dependencies 29 | run: npm install 30 | 31 | - name: Run Tests 32 | run: npm run test 33 | 34 | # Uncomment to add Codecov support / setup Codecov / add coverage badge to README 35 | # - name: Upload coverage to Codecov 36 | # uses: codecov/codecov-action@v3 37 | # with: 38 | # token: ${{ secrets.CODECOV_TOKEN }} 39 | # flags: unittests 40 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | coverage 3 | /.dts 4 | /html 5 | /.idea 6 | -------------------------------------------------------------------------------- /.ncurc.cjs: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | module.exports = { 4 | reject: [ 5 | ] 6 | }; 7 | -------------------------------------------------------------------------------- /LICENSE-MIT.txt: -------------------------------------------------------------------------------- 1 | Copyright JS Foundation and other contributors, https://js.foundation 2 | Copyright (c) 2021 Brett Zamir 3 | 4 | Permission is hereby granted, free of charge, to any person obtaining a copy 5 | of this software and associated documentation files (the "Software"), to deal 6 | in the Software without restriction, including without limitation the rights 7 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 8 | copies of the Software, and to permit persons to whom the Software is 9 | furnished to do so, subject to the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be included in 12 | all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 17 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 19 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 20 | THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /docs/.nojekyll: -------------------------------------------------------------------------------- 1 | TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false. -------------------------------------------------------------------------------- /docs/assets/dmt/dmt-component-data.js: -------------------------------------------------------------------------------- 1 | globalThis.dmtComponentDataBCMP = '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'; -------------------------------------------------------------------------------- /docs/assets/dmt/dmt-search.cmp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/es-joy/jsdoccomment/4b682d0db1f7374ac41c1a5cbbdd54101ae2ec8a/docs/assets/dmt/dmt-search.cmp -------------------------------------------------------------------------------- /docs/assets/dmt/icons/service/github.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/es-joy/jsdoccomment/4b682d0db1f7374ac41c1a5cbbdd54101ae2ec8a/docs/assets/dmt/icons/service/github.png -------------------------------------------------------------------------------- /docs/assets/dmt/icons/service/npm.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/es-joy/jsdoccomment/4b682d0db1f7374ac41c1a5cbbdd54101ae2ec8a/docs/assets/dmt/icons/service/npm.png -------------------------------------------------------------------------------- /docs/assets/highlight.css: -------------------------------------------------------------------------------- 1 | :root { 2 | --light-hl-0: #795E26; 3 | --dark-hl-0: #DCDCAA; 4 | --light-hl-1: #000000; 5 | --dark-hl-1: #D4D4D4; 6 | --light-hl-2: #A31515; 7 | --dark-hl-2: #CE9178; 8 | --light-code-background: #FFFFFF; 9 | --dark-code-background: #1E1E1E; 10 | } 11 | 12 | @media (prefers-color-scheme: light) { :root { 13 | --hl-0: var(--light-hl-0); 14 | --hl-1: var(--light-hl-1); 15 | --hl-2: var(--light-hl-2); 16 | --code-background: var(--light-code-background); 17 | } } 18 | 19 | @media (prefers-color-scheme: dark) { :root { 20 | --hl-0: var(--dark-hl-0); 21 | --hl-1: var(--dark-hl-1); 22 | --hl-2: var(--dark-hl-2); 23 | --code-background: var(--dark-code-background); 24 | } } 25 | 26 | :root[data-theme='light'] { 27 | --hl-0: var(--light-hl-0); 28 | --hl-1: var(--light-hl-1); 29 | --hl-2: var(--light-hl-2); 30 | --code-background: var(--light-code-background); 31 | } 32 | 33 | :root[data-theme='dark'] { 34 | --hl-0: var(--dark-hl-0); 35 | --hl-1: var(--dark-hl-1); 36 | --hl-2: var(--dark-hl-2); 37 | --code-background: var(--dark-code-background); 38 | } 39 | 40 | .hl-0 { color: var(--hl-0); } 41 | .hl-1 { color: var(--hl-1); } 42 | .hl-2 { color: var(--hl-2); } 43 | pre, code { background: var(--code-background); } 44 | -------------------------------------------------------------------------------- /docs/functions/catharsisTransform.html: -------------------------------------------------------------------------------- 1 | catharsisTransform | @es-joy/jsdoccomment
2 |

    Function catharsisTransform

    • Parameters

      Returns CatharsisParseResult

    -------------------------------------------------------------------------------- /docs/functions/commentHandler.html: -------------------------------------------------------------------------------- 1 | commentHandler | @es-joy/jsdoccomment
    2 |

      Function commentHandler

      -------------------------------------------------------------------------------- /docs/functions/getFollowingComment.html: -------------------------------------------------------------------------------- 1 | getFollowingComment | @es-joy/jsdoccomment
      2 |

        Function getFollowingComment

        • Checks for the presence of a comment following the given node and 3 | returns it.

          4 |

          This method is experimental.

          5 |

          Parameters

          • sourceCode: SourceCode
          • astNode: ESLintOrTSNode

            The AST node to get 6 | the comment for.

            7 |

          Returns Token | null

          The comment token containing the comment 8 | for the given node or null if not found.

          9 |
        -------------------------------------------------------------------------------- /docs/functions/getReducedASTNode.html: -------------------------------------------------------------------------------- 1 | getReducedASTNode | @es-joy/jsdoccomment
        2 |

          Function getReducedASTNode

          • Reduces the provided node to the appropriate node for evaluating 3 | JSDoc comment status.

            4 |

            Parameters

            • node: ESLintOrTSNode

              An AST node.

              5 |
            • sourceCode: SourceCode

              The ESLint SourceCode.

              6 |

            Returns ESLintOrTSNode

            The AST node that 7 | can be evaluated for appropriate JSDoc comments.

            8 |
          -------------------------------------------------------------------------------- /docs/functions/hasSeeWithLink.html: -------------------------------------------------------------------------------- 1 | hasSeeWithLink | @es-joy/jsdoccomment
          2 |

            Function hasSeeWithLink

            • Parameters

              • spec: Spec

              Returns boolean

            -------------------------------------------------------------------------------- /docs/functions/identityTransformRules.html: -------------------------------------------------------------------------------- 1 | identityTransformRules | @es-joy/jsdoccomment
            2 |

              Function identityTransformRules

              -------------------------------------------------------------------------------- /docs/functions/jtpTransform.html: -------------------------------------------------------------------------------- 1 | jtpTransform | @es-joy/jsdoccomment
              2 |

                Function jtpTransform

                • Parameters

                  Returns JtpResult

                -------------------------------------------------------------------------------- /docs/functions/parse.html: -------------------------------------------------------------------------------- 1 | parse | @es-joy/jsdoccomment
                2 |

                  Function parse

                  -------------------------------------------------------------------------------- /docs/functions/parseInlineTags.html: -------------------------------------------------------------------------------- 1 | parseInlineTags | @es-joy/jsdoccomment
                  2 |

                    Function parseInlineTags

                    • Splits the {@prefix} from remaining Spec.lines[].token.description 3 | into the inlineTags tokens, and populates spec.inlineTags

                      4 |

                      Parameters

                      • block: Block

                      Returns JsdocBlockWithInline

                    -------------------------------------------------------------------------------- /docs/functions/stringify.html: -------------------------------------------------------------------------------- 1 | stringify | @es-joy/jsdoccomment
                    2 |

                      Function stringify

                      • Parameters

                        Returns string

                      -------------------------------------------------------------------------------- /docs/functions/stringifyRules.html: -------------------------------------------------------------------------------- 1 | stringifyRules | @es-joy/jsdoccomment
                      2 |

                        Function stringifyRules

                        -------------------------------------------------------------------------------- /docs/functions/tryParse.html: -------------------------------------------------------------------------------- 1 | tryParse | @es-joy/jsdoccomment
                        2 |

                          Function tryParse

                          • This function tries to parse the given expression in multiple modes and returns the first successful 3 | RootResult. By default it tries 'typescript', 'closure' and 'jsdoc' in this order. If 4 | no mode was successful it throws the error that was produced by the last parsing attempt.

                            5 |

                            Parameters

                            Returns RootResult

                          -------------------------------------------------------------------------------- /docs/modules/jsdocVisitorKeys.html: -------------------------------------------------------------------------------- 1 | jsdocVisitorKeys | @es-joy/jsdoccomment
                          2 |

                            Namespace jsdocVisitorKeys

                            3 | 4 |

                            5 | Index 6 |

                            7 |
                            8 |
                            9 |

                            Variables

                            15 |
                            -------------------------------------------------------------------------------- /docs/types/CommentHandler-1.html: -------------------------------------------------------------------------------- 1 | CommentHandler | @es-joy/jsdoccomment
                            2 |

                              Type Alias CommentHandler

                              CommentHandler: ((commentSelector: string, jsdoc: JsdocBlockWithInline) => boolean)
                              -------------------------------------------------------------------------------- /docs/types/CommentParserTokenizer.html: -------------------------------------------------------------------------------- 1 | CommentParserTokenizer | @es-joy/jsdoccomment
                              2 |

                                Type Alias CommentParserTokenizer

                                CommentParserTokenizer: ((spec: comment_parser.Spec) => comment_parser.Spec)

                                Can't import comment-parser/es6/parser/tokenizers/index.js, 3 | so we redefine here.

                                4 |
                                -------------------------------------------------------------------------------- /docs/types/ESLintOrTSNode.html: -------------------------------------------------------------------------------- 1 | ESLintOrTSNode | @es-joy/jsdoccomment
                                2 |

                                  Type Alias ESLintOrTSNode

                                  ESLintOrTSNode: eslint.Rule.Node | _typescript_eslint_types.TSESTree.Node
                                  -------------------------------------------------------------------------------- /docs/types/ESTreeToStringOptions.html: -------------------------------------------------------------------------------- 1 | ESTreeToStringOptions | @es-joy/jsdoccomment
                                  2 |

                                    Type Alias ESTreeToStringOptions

                                    ESTreeToStringOptions: {
                                        preferRawType?: boolean;
                                    }
                                    -------------------------------------------------------------------------------- /docs/types/InlineTag.html: -------------------------------------------------------------------------------- 1 | InlineTag | @es-joy/jsdoccomment
                                    2 |

                                      Type Alias InlineTag

                                      InlineTag: JsdocInlineTagNoType & {
                                          end: number;
                                          start: number;
                                      }
                                      -------------------------------------------------------------------------------- /docs/types/Integer.html: -------------------------------------------------------------------------------- 1 | Integer | @es-joy/jsdoccomment
                                      2 |

                                        Type Alias Integer

                                        Integer: number
                                        -------------------------------------------------------------------------------- /docs/types/JsdocDescriptionLine.html: -------------------------------------------------------------------------------- 1 | JsdocDescriptionLine | @es-joy/jsdoccomment
                                        2 |

                                          Type Alias JsdocDescriptionLine

                                          JsdocDescriptionLine: {
                                              delimiter: string;
                                              description: string;
                                              initial: string;
                                              postDelimiter: string;
                                              type: "JsdocDescriptionLine";
                                          }
                                          -------------------------------------------------------------------------------- /docs/types/JsdocInlineTag.html: -------------------------------------------------------------------------------- 1 | JsdocInlineTag | @es-joy/jsdoccomment
                                          2 |

                                            Type Alias JsdocInlineTag

                                            JsdocInlineTag: JsdocInlineTagNoType & {
                                                type: "JsdocInlineTag";
                                            }
                                            -------------------------------------------------------------------------------- /docs/types/JsdocInlineTagNoType.html: -------------------------------------------------------------------------------- 1 | JsdocInlineTagNoType | @es-joy/jsdoccomment
                                            2 |

                                              Type Alias JsdocInlineTagNoType

                                              JsdocInlineTagNoType: {
                                                  format:
                                                      | "pipe"
                                                      | "plain"
                                                      | "prefix"
                                                      | "space";
                                                  namepathOrURL: string;
                                                  tag: string;
                                                  text: string;
                                              }
                                              -------------------------------------------------------------------------------- /docs/types/JsdocTagWithInline.html: -------------------------------------------------------------------------------- 1 | JsdocTagWithInline | @es-joy/jsdoccomment
                                              2 |

                                                Type Alias JsdocTagWithInline

                                                JsdocTagWithInline: comment_parser.Spec & {
                                                    inlineTags: (JsdocInlineTagNoType & {
                                                        line?: Integer;
                                                    })[];
                                                    line?: Integer;
                                                }
                                                -------------------------------------------------------------------------------- /docs/types/JsdocTypeLine.html: -------------------------------------------------------------------------------- 1 | JsdocTypeLine | @es-joy/jsdoccomment
                                                2 |

                                                  Type Alias JsdocTypeLine

                                                  JsdocTypeLine: {
                                                      delimiter: string;
                                                      initial: string;
                                                      postDelimiter: string;
                                                      rawType: string;
                                                      type: "JsdocTypeLine";
                                                  }
                                                  -------------------------------------------------------------------------------- /docs/types/NonRootResult.html: -------------------------------------------------------------------------------- 1 | NonRootResult | @es-joy/jsdoccomment
                                                  2 |

                                                    Type Alias NonRootResult

                                                    NonRootResult:
                                                        | RootResult
                                                        | PropertyResult
                                                        | ObjectFieldResult
                                                        | JsdocObjectFieldResult
                                                        | KeyValueResult
                                                        | MappedTypeResult
                                                        | IndexSignatureResult

                                                    A parse sub result that might not be a valid type expression on its own.

                                                    3 |
                                                    -------------------------------------------------------------------------------- /docs/types/ParseMode.html: -------------------------------------------------------------------------------- 1 | ParseMode | @es-joy/jsdoccomment
                                                    2 |

                                                      Type Alias ParseMode

                                                      ParseMode: "closure" | "jsdoc" | "typescript"
                                                      -------------------------------------------------------------------------------- /docs/types/QuoteStyle.html: -------------------------------------------------------------------------------- 1 | QuoteStyle | @es-joy/jsdoccomment
                                                      2 |

                                                        Type Alias QuoteStyle

                                                        QuoteStyle: "single" | "double"
                                                        -------------------------------------------------------------------------------- /docs/types/SpecialNamePathType.html: -------------------------------------------------------------------------------- 1 | SpecialNamePathType | @es-joy/jsdoccomment
                                                        2 |

                                                          Type Alias SpecialNamePathType

                                                          SpecialNamePathType: "module" | "event" | "external"
                                                          -------------------------------------------------------------------------------- /docs/types/Token.html: -------------------------------------------------------------------------------- 1 | Token | @es-joy/jsdoccomment
                                                          2 |

                                                            Type Alias Token

                                                            Token: eslint.AST.Token | estree.Comment | {
                                                                range: [number, number];
                                                                type:
                                                                    | eslint.AST.TokenType
                                                                    | "Line"
                                                                    | "Block"
                                                                    | "Shebang";
                                                                value: string;
                                                            }
                                                            -------------------------------------------------------------------------------- /docs/types/TransformFunction.html: -------------------------------------------------------------------------------- 1 | TransformFunction | @es-joy/jsdoccomment
                                                            2 |

                                                              Type Alias TransformFunction<TransformResult>

                                                              TransformFunction<TransformResult>: ((parseResult: NonRootResult) => TransformResult)

                                                              Type Parameters

                                                              • TransformResult
                                                              -------------------------------------------------------------------------------- /docs/types/TransformRule.html: -------------------------------------------------------------------------------- 1 | TransformRule | @es-joy/jsdoccomment
                                                              2 |

                                                                Type Alias TransformRule<TransformResult, InputType>

                                                                TransformRule<TransformResult, InputType>: ((parseResult: InputType, transform: TransformFunction<TransformResult>) => TransformResult)

                                                                Type Parameters

                                                                -------------------------------------------------------------------------------- /docs/types/TransformRules.html: -------------------------------------------------------------------------------- 1 | TransformRules | @es-joy/jsdoccomment
                                                                2 |

                                                                  Type Alias TransformRules<TransformResult>

                                                                  TransformRules<TransformResult>: {
                                                                      [P in NonRootResult as P["type"]]: TransformRule<TransformResult, P>
                                                                  }

                                                                  Type Parameters

                                                                  • TransformResult
                                                                  -------------------------------------------------------------------------------- /docs/types/VisitorKeys.html: -------------------------------------------------------------------------------- 1 | VisitorKeys | @es-joy/jsdoccomment
                                                                  2 |

                                                                    Type Alias VisitorKeys

                                                                    VisitorKeys: {
                                                                        [P in NonRootResult as P["type"]]: (keyof P)[]
                                                                    }
                                                                    -------------------------------------------------------------------------------- /docs/types/int.html: -------------------------------------------------------------------------------- 1 | int | @es-joy/jsdoccomment
                                                                    2 |

                                                                      Type Alias int

                                                                      int: number
                                                                      -------------------------------------------------------------------------------- /docs/variables/defaultNoNames.html: -------------------------------------------------------------------------------- 1 | defaultNoNames | @es-joy/jsdoccomment
                                                                      2 |

                                                                        Variable defaultNoNamesConst

                                                                        defaultNoNames: string[]
                                                                        -------------------------------------------------------------------------------- /docs/variables/defaultNoTypes.html: -------------------------------------------------------------------------------- 1 | defaultNoTypes | @es-joy/jsdoccomment
                                                                        2 |

                                                                          Variable defaultNoTypesConst

                                                                          defaultNoTypes: string[]
                                                                          -------------------------------------------------------------------------------- /docs/variables/jsdocTypeVisitorKeys.html: -------------------------------------------------------------------------------- 1 | jsdocTypeVisitorKeys | @es-joy/jsdoccomment
                                                                          2 |

                                                                            Variable jsdocTypeVisitorKeysConst

                                                                            jsdocTypeVisitorKeys: VisitorKeys
                                                                            -------------------------------------------------------------------------------- /docs/variables/jsdocVisitorKeys.JsdocBlock.html: -------------------------------------------------------------------------------- 1 | JsdocBlock | @es-joy/jsdoccomment
                                                                            2 |

                                                                            Variable JsdocBlock

                                                                            JsdocBlock: string[]
                                                                            -------------------------------------------------------------------------------- /docs/variables/jsdocVisitorKeys.JsdocDescriptionLine.html: -------------------------------------------------------------------------------- 1 | JsdocDescriptionLine | @es-joy/jsdoccomment
                                                                            2 |

                                                                            Variable JsdocDescriptionLine

                                                                            JsdocDescriptionLine: any[]
                                                                            -------------------------------------------------------------------------------- /docs/variables/jsdocVisitorKeys.JsdocInlineTag.html: -------------------------------------------------------------------------------- 1 | JsdocInlineTag | @es-joy/jsdoccomment
                                                                            2 |

                                                                            Variable JsdocInlineTag

                                                                            JsdocInlineTag: any[]
                                                                            -------------------------------------------------------------------------------- /docs/variables/jsdocVisitorKeys.JsdocTag.html: -------------------------------------------------------------------------------- 1 | JsdocTag | @es-joy/jsdoccomment
                                                                            2 |

                                                                            Variable JsdocTag

                                                                            JsdocTag: string[]
                                                                            -------------------------------------------------------------------------------- /docs/variables/jsdocVisitorKeys.JsdocTypeLine.html: -------------------------------------------------------------------------------- 1 | JsdocTypeLine | @es-joy/jsdoccomment
                                                                            2 |

                                                                            Variable JsdocTypeLine

                                                                            JsdocTypeLine: any[]
                                                                            -------------------------------------------------------------------------------- /eslint.config.js: -------------------------------------------------------------------------------- 1 | import ashNazg from 'eslint-config-ash-nazg'; 2 | import jsdoc from 'eslint-plugin-jsdoc'; 3 | 4 | export default [ 5 | { 6 | ignores: [ 7 | 'coverage', 8 | 'docs', 9 | 'dist', 10 | 'html' 11 | ] 12 | }, 13 | ...ashNazg(['sauron']), 14 | ...jsdoc.configs.examples, 15 | // { 16 | // files: ['**/*.md/*.js'], 17 | // rules: { 18 | // // Enable or disable rules for `@example` JavaScript here 19 | // } 20 | // }, 21 | { 22 | files: ['test/**'], 23 | languageOptions: { 24 | globals: { 25 | // Not chai 26 | expect: 'readonly' 27 | } 28 | } 29 | }, 30 | { 31 | rules: { 32 | // https://github.com/benmosher/eslint-plugin-import/issues/1868 33 | 'import/no-unresolved': 'off' 34 | } 35 | } 36 | ]; 37 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@es-joy/jsdoccomment", 3 | "version": "0.50.2", 4 | "author": "Brett Zamir ", 5 | "contributors": [], 6 | "description": "Maintained replacement for ESLint's deprecated SourceCode#getJSDocComment along with other jsdoc utilities", 7 | "license": "MIT", 8 | "keywords": [ 9 | "ast", 10 | "comment", 11 | "estree", 12 | "jsdoc", 13 | "parser", 14 | "eslint", 15 | "sourcecode" 16 | ], 17 | "type": "module", 18 | "types": "./dist/index.d.ts", 19 | "exports": { 20 | ".": { 21 | "import": { 22 | "types": "./dist/index.d.ts", 23 | "default": "./src/index.js" 24 | }, 25 | "require": { 26 | "types": "./dist/index.d.cts", 27 | "default": "./dist/index.cjs.cjs" 28 | } 29 | } 30 | }, 31 | "browserslist": [ 32 | "defaults, not op_mini all" 33 | ], 34 | "scripts": { 35 | "build": "rollup -c && npm run types", 36 | "docs": "typedoc-pkg --api-link es", 37 | "eslint": "eslint .", 38 | "lint": "npm run eslint --", 39 | "open": "open ./coverage/index.html", 40 | "prepublishOnly": "pnpm i && npm run build", 41 | "test": "npm run lint && npm run build && npm run test-cov", 42 | "test-ui": "vitest --ui --coverage", 43 | "test-cov": "vitest --coverage", 44 | "tsc": "tsc", 45 | "types": "esm-d-ts gen ./src/index.js --output ./dist/index.d.ts --emitCTS" 46 | }, 47 | "typedocOptions": { 48 | "dmtLinksService": { 49 | "GitHub": "https://github.com/es-joy/jsdoccomment", 50 | "NPM": "https://www.npmjs.com/package/@es-joy/jsdoccomment" 51 | } 52 | }, 53 | "repository": { 54 | "type": "git", 55 | "url": "git+https://github.com/es-joy/jsdoccomment.git" 56 | }, 57 | "bugs": { 58 | "url": "https://github.com/es-joy/jsdoccomment/issues" 59 | }, 60 | "homepage": "https://github.com/es-joy/jsdoccomment", 61 | "engines": { 62 | "node": ">=18" 63 | }, 64 | "dependencies": { 65 | "@types/estree": "^1.0.6", 66 | "@typescript-eslint/types": "^8.11.0", 67 | "comment-parser": "1.4.1", 68 | "esquery": "^1.6.0", 69 | "jsdoc-type-pratt-parser": "~4.1.0" 70 | }, 71 | "devDependencies": { 72 | "@babel/core": "^7.25.9", 73 | "@babel/plugin-syntax-class-properties": "^7.12.13", 74 | "@babel/preset-env": "^7.25.9", 75 | "@rollup/plugin-babel": "^6.0.4", 76 | "@types/esquery": "^1.5.4", 77 | "@types/estraverse": "^5.1.7", 78 | "@typescript-eslint/visitor-keys": "^8.11.0", 79 | "@typhonjs-build-test/esm-d-ts": "^0.3.0-next.9", 80 | "@typhonjs-typedoc/typedoc-pkg": "^0.1.2", 81 | "@vitest/coverage-v8": "^2.1.3", 82 | "@vitest/ui": "^2.1.3", 83 | "eslint": "^9.13.0", 84 | "eslint-config-ash-nazg": "36.12.0", 85 | "espree": "^10.2.0", 86 | "estraverse": "^5.3.0", 87 | "rollup": "^4.24.0", 88 | "typescript": "^5.6.3", 89 | "typescript-eslint": "^8.11.0", 90 | "vitest": "^2.1.3" 91 | }, 92 | "files": [ 93 | "/dist", 94 | "/src", 95 | "CHANGES.md", 96 | "LICENSE-MIT.txt" 97 | ] 98 | } 99 | -------------------------------------------------------------------------------- /rollup.config.js: -------------------------------------------------------------------------------- 1 | import {babel} from '@rollup/plugin-babel'; 2 | 3 | /** 4 | * @external RollupConfig 5 | * @type {PlainObject} 6 | * @see {@link https://rollupjs.org/guide/en#big-list-of-options} 7 | */ 8 | 9 | /** 10 | * @param {PlainObject} config 11 | * @param {string} config.input 12 | * @param {string} [config.format] 13 | * @param {boolean} [config.minifying] 14 | * @returns {RollupConfig} 15 | */ 16 | function getRollupObject ({input, minifying, format = 'umd'} = {}) { 17 | const nonMinified = { 18 | input: `src/${input}`, 19 | external: [ 20 | 'esquery', 'jsdoc-type-pratt-parser', 'comment-parser' 21 | ], 22 | output: { 23 | name: 'JsdocComment', 24 | format, 25 | sourcemap: minifying, 26 | file: `dist/${input.replace(/\.js$/u, `.${format}`)}${ 27 | minifying ? '.min' : '' 28 | }.${format === 'cjs' || format === 'umd' ? 'c' : ''}js` 29 | }, 30 | plugins: [ 31 | babel({ 32 | babelHelpers: 'bundled' 33 | }) 34 | ] 35 | }; 36 | /* 37 | if (minifying) { 38 | nonMinified.plugins.push(terser()); 39 | } 40 | */ 41 | return nonMinified; 42 | } 43 | 44 | export default [ 45 | getRollupObject({ 46 | input: 'index.js', format: 'cjs' 47 | }) 48 | ]; 49 | -------------------------------------------------------------------------------- /src/commentHandler.js: -------------------------------------------------------------------------------- 1 | import esquery from 'esquery'; 2 | 3 | import { 4 | visitorKeys as jsdocTypePrattParserVisitorKeys 5 | } from 'jsdoc-type-pratt-parser'; 6 | 7 | import { 8 | commentParserToESTree, jsdocVisitorKeys 9 | } from './commentParserToESTree.js'; 10 | 11 | /** 12 | * @param {{[name: string]: any}} settings 13 | * @returns {import('.').CommentHandler} 14 | */ 15 | const commentHandler = (settings) => { 16 | /** 17 | * @type {import('.').CommentHandler} 18 | */ 19 | return (commentSelector, jsdoc) => { 20 | const {mode} = settings; 21 | 22 | const selector = esquery.parse(commentSelector); 23 | 24 | const ast = commentParserToESTree(jsdoc, mode); 25 | 26 | const castAst = /** @type {unknown} */ (ast); 27 | 28 | return esquery.matches(/** @type {import('estree').Node} */ ( 29 | castAst 30 | ), selector, undefined, { 31 | visitorKeys: { 32 | ...jsdocTypePrattParserVisitorKeys, 33 | ...jsdocVisitorKeys 34 | } 35 | }); 36 | }; 37 | }; 38 | 39 | export {commentHandler}; 40 | -------------------------------------------------------------------------------- /src/index.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @typedef {import('./commentParserToESTree').JsdocInlineTagNoType & { 3 | * start: number, 4 | * end: number, 5 | * }} InlineTag 6 | */ 7 | 8 | /** 9 | * @typedef {import('comment-parser').Spec & { 10 | * line?: import('./commentParserToESTree').Integer, 11 | * inlineTags: (import('./commentParserToESTree').JsdocInlineTagNoType & { 12 | * line?: import('./commentParserToESTree').Integer 13 | * })[] 14 | * }} JsdocTagWithInline 15 | */ 16 | 17 | /** 18 | * Expands on comment-parser's `Block` interface. 19 | * @typedef {{ 20 | * description: string, 21 | * source: import('comment-parser').Line[], 22 | * problems: import('comment-parser').Problem[], 23 | * tags: JsdocTagWithInline[], 24 | * inlineTags: (import('./commentParserToESTree').JsdocInlineTagNoType & { 25 | * line?: import('./commentParserToESTree').Integer 26 | * })[] 27 | * }} JsdocBlockWithInline 28 | */ 29 | 30 | /** 31 | * @typedef {{preferRawType?: boolean}} ESTreeToStringOptions 32 | */ 33 | 34 | /** 35 | * @callback CommentHandler 36 | * @param {string} commentSelector 37 | * @param {import('.').JsdocBlockWithInline} jsdoc 38 | * @returns {boolean} 39 | */ 40 | 41 | export {visitorKeys as jsdocTypeVisitorKeys} from 'jsdoc-type-pratt-parser'; 42 | 43 | export * from 'jsdoc-type-pratt-parser'; 44 | 45 | export * from './commentHandler.js'; 46 | export * from './commentParserToESTree.js'; 47 | export * from './estreeToString.js'; 48 | export * from './jsdoccomment.js'; 49 | export * from './parseComment.js'; 50 | export * from './parseInlineTags.js'; 51 | -------------------------------------------------------------------------------- /src/parseInlineTags.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @param {RegExpMatchArray & { 3 | * indices: { 4 | * groups: { 5 | * [key: string]: [number, number] 6 | * } 7 | * } 8 | * groups: {[key: string]: string} 9 | * }} match An inline tag regexp match. 10 | * @returns {'pipe' | 'plain' | 'prefix' | 'space'} 11 | */ 12 | function determineFormat (match) { 13 | const {separator, text} = match.groups; 14 | const [, textEnd] = match.indices.groups.text; 15 | const [tagStart] = match.indices.groups.tag; 16 | if (!text) { 17 | return 'plain'; 18 | } else if (separator === '|') { 19 | return 'pipe'; 20 | } else if (textEnd < tagStart) { 21 | return 'prefix'; 22 | } 23 | return 'space'; 24 | } 25 | 26 | /** 27 | * Extracts inline tags from a description. 28 | * @param {string} description 29 | * @returns {import('.').InlineTag[]} Array of inline tags from the description. 30 | */ 31 | function parseDescription (description) { 32 | /** @type {import('.').InlineTag[]} */ 33 | const result = []; 34 | 35 | // This could have been expressed in a single pattern, 36 | // but having two avoids a potentially exponential time regex. 37 | 38 | const prefixedTextPattern = new RegExp(/(?:\[(?[^\]]+)\])\{@(?[^}\s]+)\s?(?[^}\s|]*)\}/gu, 'gud'); 39 | // The pattern used to match for text after tag uses a negative lookbehind 40 | // on the ']' char to avoid matching the prefixed case too. 41 | const suffixedAfterPattern = new RegExp(/(?[^}\s]+)\s?(?[^}\s|]*)\s*(?[\s|])?\s*(?[^}]*)\}/gu, 'gud'); 42 | 43 | const matches = [ 44 | ...description.matchAll(prefixedTextPattern), 45 | ...description.matchAll(suffixedAfterPattern) 46 | ]; 47 | 48 | for (const mtch of matches) { 49 | const match = /** 50 | * @type {RegExpMatchArray & { 51 | * indices: { 52 | * groups: { 53 | * [key: string]: [number, number] 54 | * } 55 | * } 56 | * groups: {[key: string]: string} 57 | * }} 58 | */ ( 59 | mtch 60 | ); 61 | const {tag, namepathOrURL, text} = match.groups; 62 | const [start, end] = match.indices[0]; 63 | const format = determineFormat(match); 64 | 65 | result.push({ 66 | tag, 67 | namepathOrURL, 68 | text, 69 | format, 70 | start, 71 | end 72 | }); 73 | } 74 | 75 | return result; 76 | } 77 | 78 | /** 79 | * Splits the `{@prefix}` from remaining `Spec.lines[].token.description` 80 | * into the `inlineTags` tokens, and populates `spec.inlineTags` 81 | * @param {import('comment-parser').Block} block 82 | * @returns {import('.').JsdocBlockWithInline} 83 | */ 84 | export function parseInlineTags (block) { 85 | const inlineTags = 86 | /** 87 | * @type {(import('./commentParserToESTree').JsdocInlineTagNoType & { 88 | * line?: import('./commentParserToESTree').Integer 89 | * })[]} 90 | */ ( 91 | parseDescription(block.description) 92 | ); 93 | 94 | /** @type {import('.').JsdocBlockWithInline} */ ( 95 | block 96 | ).inlineTags = inlineTags; 97 | 98 | for (const tag of block.tags) { 99 | /** 100 | * @type {import('.').JsdocTagWithInline} 101 | */ (tag).inlineTags = parseDescription(tag.description); 102 | } 103 | return ( 104 | /** 105 | * @type {import('.').JsdocBlockWithInline} 106 | */ (block) 107 | ); 108 | } 109 | -------------------------------------------------------------------------------- /src/toCamelCase.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @param {string} str 3 | * @returns {string} 4 | */ 5 | const toCamelCase = (str) => { 6 | return str.toLowerCase().replaceAll(/^[a-z]/gu, (init) => { 7 | return init.toUpperCase(); 8 | }).replaceAll(/_(?[a-z])/gu, (_, n1, o, s, {wordInit}) => { 9 | return wordInit.toUpperCase(); 10 | }); 11 | }; 12 | 13 | export {toCamelCase}; 14 | -------------------------------------------------------------------------------- /test/commentHandler.test.js: -------------------------------------------------------------------------------- 1 | import { 2 | commentHandler, 3 | parseComment 4 | } from '../src/index.js'; 5 | 6 | describe('commentHandler', function () { 7 | it('Returns `true` with match', function () { 8 | const handler = commentHandler({ 9 | mode: 'typescript' 10 | }); 11 | 12 | const parsed = parseComment({ 13 | value: `* @property opt_a 14 | * @param {Bar|Foo} opt_b 15 | ` 16 | }); 17 | 18 | const result = handler( 19 | 'JSDocBlock:has(JSDocTag[tag="param"][name=/opt_/] > ' + 20 | 'JSDocTypeUnion:has(JsdocTypeName[value="Bar"]:nth-child(1)))', 21 | parsed 22 | ); 23 | 24 | expect(result).to.equal(true); 25 | }); 26 | 27 | it('Returns `false` when no match present', function () { 28 | const handler = commentHandler({ 29 | mode: 'typescript' 30 | }); 31 | 32 | const parsed = parseComment({ 33 | value: `* @property opt_a 34 | * @param {Foo|Bar} opt_b 35 | ` 36 | }); 37 | 38 | const result = handler( 39 | 'JSDocBlock:has(JSDocTag[tag="param"][name=/opt_/] > ' + 40 | 'JSDocTypeUnion:has(JsdocTypeName[value="Bar"]:nth-child(1)))', 41 | parsed 42 | ); 43 | 44 | expect(result).to.equal(false); 45 | }); 46 | }); 47 | -------------------------------------------------------------------------------- /test/getJSDocComment.test.js: -------------------------------------------------------------------------------- 1 | import {RuleTester} from 'eslint'; 2 | import {getJSDocComment} from '../src/index.js'; 3 | 4 | /** 5 | * @param {import('eslint').Rule.RuleContext} ctxt 6 | */ 7 | const getSettings = (ctxt) => { 8 | return { 9 | maxLines: Number(ctxt.settings.jsdoc?.maxLines ?? 1), 10 | minLines: Number(ctxt.settings.jsdoc?.minLines ?? 0) 11 | }; 12 | }; 13 | 14 | /** @type {import('eslint').Rule.RuleModule} */ 15 | const rule = { 16 | create (ctxt) { 17 | const {sourceCode} = ctxt; 18 | const settings = getSettings(ctxt); 19 | if (!settings) { 20 | return {}; 21 | } 22 | 23 | return { 24 | ArrowFunctionExpression (node) { 25 | const comment = getJSDocComment(sourceCode, node, settings); 26 | if (comment !== null) { 27 | return; 28 | } 29 | ctxt.report({ 30 | messageId: 'missingJsDoc', 31 | node 32 | }); 33 | }, 34 | Property (node) { 35 | const comment = getJSDocComment(sourceCode, node, settings); 36 | if (comment !== null) { 37 | return; 38 | } 39 | ctxt.report({ 40 | messageId: 'missingJsDoc', 41 | node 42 | }); 43 | }, 44 | ObjectExpression (node) { 45 | const comment = getJSDocComment(sourceCode, node, settings); 46 | if (comment !== null) { 47 | return; 48 | } 49 | ctxt.report({ 50 | messageId: 'missingJsDoc', 51 | node 52 | }); 53 | } 54 | }; 55 | }, 56 | meta: { 57 | messages: { 58 | missingJsDoc: 'Missing JSDoc comment.' 59 | }, 60 | type: 'layout' 61 | } 62 | }; 63 | 64 | const ruleTester = new RuleTester(); 65 | 66 | ruleTester.run('getJSDocComment', rule, { 67 | invalid: [{ 68 | code: 'var a = {};', 69 | errors: [{messageId: 'missingJsDoc'}] 70 | }, { 71 | code: ` 72 | var comment = /** @type {EsprimaComment} */ ({ 73 | value: text 74 | }); 75 | `, 76 | errors: [{messageId: 'missingJsDoc', type: 'Property'}] 77 | }], 78 | valid: [{ 79 | code: ` 80 | /** Doc */ 81 | var a = {}; 82 | ` 83 | }, { 84 | code: ` 85 | /** Doc */ 86 | // eslint-disable-next-line no-var 87 | var a = {}; 88 | ` 89 | }, { 90 | code: ` 91 | app.use( 92 | /** @type {express.ErrorRequestHandler} */ 93 | ( 94 | (err, req, res, next) => { 95 | // foo 96 | } 97 | ) 98 | ); 99 | ` 100 | }, { 101 | code: ` 102 | app.use( 103 | ( 104 | /** @param err */ 105 | (err, req, res, next) => { 106 | // foo 107 | } 108 | ) 109 | ); 110 | ` 111 | }] 112 | }); 113 | -------------------------------------------------------------------------------- /test/roundTripParsing.test.js: -------------------------------------------------------------------------------- 1 | import { 2 | commentParserToESTree, 3 | estreeToString, 4 | parseComment 5 | } from '../src/index.js'; 6 | 7 | import { 8 | commentBlocks, 9 | compactResults, 10 | compactResultsPratt, 11 | preserveResults, 12 | preserveResultsPratt 13 | } from './fixture/roundTripData.js'; 14 | 15 | // The goal in the following data defined tests is round trip testing from 16 | // parseComment -> commentParserToESTree -> estreeToString. 17 | // `commentBlocks` provides the source comment block and `compactResults` 18 | // `preserveResults` provides the respective results for `compact` and 19 | // `preserve` `spacing` option for `commentParserToESTree`. 20 | 21 | /** 22 | * Converts `JsdocDescriptionLine[]` to a string description removing 23 | * any leading white space or delimiter. 24 | * 25 | * @param {( 26 | * import('../src/commentParserToESTree').JsdocDescriptionLine[]) 27 | * } descriptionLines - 28 | * @returns {string} Complete description line string. 29 | */ 30 | const descriptionLinesToString = (descriptionLines) => { 31 | let result = ''; 32 | 33 | for (const descriptionLine of descriptionLines) { 34 | const desc = estreeToString(descriptionLine).replace(/^\s*\**\s*/u, ''); 35 | result += !result ? desc : `\n${desc}`; 36 | } 37 | 38 | return result; 39 | }; 40 | 41 | describe('Round Trip Parsing', () => { 42 | describe('`compact` option', () => { 43 | // eslint-disable-next-line unicorn/no-for-loop -- For loop used for index. 44 | for (let i = 0; i < commentBlocks.length; i++) { 45 | it(`commentBlock[${i}]`, () => { 46 | const parsedComment = parseComment(commentBlocks[i]); 47 | 48 | const ast = commentParserToESTree(parsedComment, 'jsdoc'); 49 | 50 | // Check description lines against `ast.description`. 51 | expect(ast.description).to.equal( 52 | descriptionLinesToString(ast.descriptionLines) 53 | ); 54 | 55 | // Check tag description lines against `tag.description`. 56 | for (const tag of ast.tags) { 57 | expect(tag.description).to.equal( 58 | descriptionLinesToString(tag.descriptionLines) 59 | ); 60 | } 61 | 62 | const result = estreeToString(ast, {preferRawType: true}); 63 | 64 | expect(result).to.equal(compactResults[i]); 65 | 66 | const resultPratt = estreeToString(ast); 67 | 68 | expect(resultPratt).to.equal(compactResultsPratt[i]); 69 | }); 70 | } 71 | }); 72 | 73 | describe('`preserve` option', () => { 74 | // eslint-disable-next-line unicorn/no-for-loop -- For loop used for index. 75 | for (let i = 0; i < commentBlocks.length; i++) { 76 | it(`commentBlock[${i}]`, () => { 77 | const parsedComment = parseComment(commentBlocks[i]); 78 | 79 | const ast = commentParserToESTree(parsedComment, 'jsdoc', 80 | {spacing: 'preserve'}); 81 | 82 | expect(ast.description).to.equal( 83 | descriptionLinesToString(ast.descriptionLines) 84 | ); 85 | 86 | for (const tag of ast.tags) { 87 | expect(tag.description).to.equal( 88 | descriptionLinesToString(tag.descriptionLines) 89 | ); 90 | } 91 | 92 | const result = estreeToString(ast, {preferRawType: true}); 93 | 94 | expect(result).to.equal(preserveResults[i]); 95 | 96 | const resultPratt = estreeToString(ast); 97 | 98 | expect(resultPratt).to.equal(preserveResultsPratt[i]); 99 | }); 100 | } 101 | }); 102 | }); 103 | -------------------------------------------------------------------------------- /test/toCamelCase.test.js: -------------------------------------------------------------------------------- 1 | import {toCamelCase} from '../src/toCamelCase.js'; 2 | 3 | describe('toCamelCase', function () { 4 | it('work with underscores', function () { 5 | expect(toCamelCase('test_one')).to.equal('TestOne'); 6 | }); 7 | }); 8 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "lib": ["esnext", "dom"], 4 | "moduleResolution": "Bundler", 5 | "module": "esnext", 6 | "target": "esnext", 7 | "allowJs": true, 8 | "checkJs": true, 9 | "noEmit": true, 10 | "strict": true, 11 | "skipLibCheck": true, 12 | "types": ["vitest/globals"] 13 | }, 14 | "include": ["src/**/*.js", "test/**/*.js", "typings/espree.d.ts"], 15 | "exclude": ["node_modules"] 16 | } 17 | -------------------------------------------------------------------------------- /typings/espree.d.ts: -------------------------------------------------------------------------------- 1 | declare module 'espree' { 2 | type Config = { 3 | ecmaVersion: number, 4 | comment: boolean, 5 | tokens: boolean, 6 | range: boolean, 7 | loc: boolean 8 | } 9 | function parse(code: string, config: Config): import('eslint').AST.Program; 10 | } 11 | -------------------------------------------------------------------------------- /vitest.config.js: -------------------------------------------------------------------------------- 1 | import { 2 | configDefaults, 3 | defineConfig 4 | } from 'vitest/config'; 5 | 6 | export default defineConfig({ 7 | test: { 8 | exclude: [...configDefaults.exclude], 9 | include: ['./test/**/*.test.js'], 10 | coverage: { 11 | include: ['src/**'], 12 | exclude: ['test/**'], 13 | provider: 'v8', 14 | reporter: ['text', 'json', 'html'] 15 | }, 16 | reporters: ['default', 'html'], 17 | globals: true 18 | } 19 | }); 20 | --------------------------------------------------------------------------------