chore: add .d.cts file / add type dependencies (#19)

BREAKING CHANGE:

Require Node 18+

Also:
- test(ci): drop Node 16.x and add Node 22.x

.babelrc.json

@@ -7,7 +7,7 @@
       "@babel/preset-env",
       {
         "targets": {
-          "node": 10
+          "node": 18
         }
       }
     ]

.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        node-version: [16.x, 18.x, 20.x]
+        node-version: [18.x, 20.x, 22.x]
 
     runs-on: ${{ matrix.os }}
 

dist/index.d.cts

@@ -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,
+};