refactor: migrate deprecated doctrine to comment-parser

close #313

Author: JounQin

.changeset/kind-bananas-poke.md

@@ -0,0 +1,5 @@
+---
+"eslint-plugin-import-x": minor
+---
+
+refactor: migrate deprecated `doctrine` to `comment-parser`

.gitignore

@@ -26,3 +26,6 @@ lib
 !.yarn/plugins
 !.yarn/releases
 !.yarn/sdks
+
+# Local test
+test.local.*

package.json

@@ -72,23 +72,22 @@
   },
   "dependencies": {
     "@pkgr/core": "^0.2.4",
-    "@types/doctrine": "^0.0.9",
-    "@typescript-eslint/utils": "^8.30.1",
+    "@typescript-eslint/utils": "^8.31.0",
+    "comment-parser": "^1.4.1",
     "debug": "^4.4.0",
-    "doctrine": "^3.0.0",
     "eslint-import-resolver-node": "^0.3.9",
     "get-tsconfig": "^4.10.0",
     "is-glob": "^4.0.3",
     "minimatch": "^9.0.3 || ^10.0.1",
     "semver": "^7.7.1",
     "stable-hash": "^0.0.5",
     "tslib": "^2.8.1",
-    "unrs-resolver": "^1.6.0"
+    "unrs-resolver": "^1.7.0"
   },
   "devDependencies": {
     "@1stg/commitlint-config": "^5.0.6",
     "@1stg/lint-staged": "^4.0.9",
-    "@1stg/prettier-config": "^5.1.3",
+    "@1stg/prettier-config": "^5.1.4",
     "@1stg/remark-preset": "^3.1.1",
     "@1stg/simple-git-hooks": "^2.0.1",
     "@1stg/tsconfig": "^3.0.3",
@@ -106,10 +105,10 @@
     "@changesets/cli": "^2.29.2",
     "@commitlint/cli": "^19.8.0",
     "@eslint/import-test-order-redirect-scoped": "link:./test/fixtures/order-redirect-scoped",
-    "@eslint/js": "^9.25.0",
+    "@eslint/js": "^9.25.1",
     "@pkgr/rollup": "^6.0.3",
     "@swc-node/jest": "^1.8.13",
-    "@swc/core": "^1.11.21",
+    "@swc/core": "^1.11.22",
     "@swc/helpers": "^0.5.17",
     "@test-scope/some-module": "link:./test/fixtures/symlinked-module",
     "@total-typescript/ts-reset": "^0.6.1",
@@ -122,26 +121,26 @@
     "@types/klaw-sync": "^6.0.5",
     "@types/node": "^22.14.1",
     "@types/pnpapi": "^0.0.5",
-    "@typescript-eslint/eslint-plugin": "^8.30.1",
-    "@typescript-eslint/parser": "^8.30.1",
-    "@typescript-eslint/rule-tester": "^8.30.1",
+    "@typescript-eslint/eslint-plugin": "^8.31.0",
+    "@typescript-eslint/parser": "^8.31.0",
+    "@typescript-eslint/rule-tester": "^8.31.0",
     "@unts/patch-package": "^8.1.1",
-    "clean-pkg-json": "^1.2.1",
-    "eslint": "^9.25.0",
+    "clean-pkg-json": "^1.3.0",
+    "eslint": "^9.25.1",
     "eslint-config-prettier": "^10.1.2",
     "eslint-doc-generator": "^2.1.2",
-    "eslint-import-resolver-typescript": "^4.3.3",
+    "eslint-import-resolver-typescript": "^4.3.4",
     "eslint-import-resolver-webpack": "^0.13.10",
     "eslint-import-test-order-redirect": "link:./test/fixtures/order-redirect",
     "eslint-plugin-eslint-plugin": "^6.4.0",
     "eslint-plugin-import-x": "link:.",
     "eslint-plugin-jest": "^28.11.0",
     "eslint-plugin-json": "^4.0.1",
-    "eslint-plugin-mdx": "^3.4.0",
+    "eslint-plugin-mdx": "^3.4.1",
     "eslint-plugin-n": "^17.17.0",
     "eslint-plugin-prettier": "^5.2.6",
     "eslint-plugin-unicorn": "^58.0.0",
-    "eslint-plugin-yml": "^1.17.0",
+    "eslint-plugin-yml": "^1.18.0",
     "eslint8.56": "npm:eslint@~8.56.0",
     "eslint9": "npm:eslint@^9.24.0",
     "globals": "^16.0.0",
@@ -150,16 +149,16 @@
     "klaw-sync": "^7.0.0",
     "nano-staged": "^0.8.0",
     "npm-run-all2": "^7.0.2",
-    "path-serializer": "^0.3.4",
+    "path-serializer": "^0.4.0",
     "prettier": "^3.5.3",
     "redux": "^5.0.1",
     "rimraf": "^6.0.1",
-    "simple-git-hooks": "^2.12.1",
+    "simple-git-hooks": "^2.13.0",
     "tinyexec": "^1.0.1",
     "ts-node": "^10.9.2",
     "type-fest": "^4.40.0",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.30.1",
+    "typescript-eslint": "^8.31.0",
     "yarn-berry-deduplicate": "^6.1.3",
     "zod": "^3.24.3"
   },

src/meta.ts

@@ -1,14 +1,10 @@
 import { createRequire } from 'node:module'
 
-import { EVAL_FILENAMES } from '@pkgr/core'
 import type { CjsRequire } from '@pkgr/core'
 
-const cjsRequire: CjsRequire =
-  typeof require === 'undefined' ||
-  // workaround for #296
-  EVAL_FILENAMES.has(__filename)
-    ? createRequire(import.meta.url)
-    : /* istanbul ignore next */ require
+const cjsRequire: CjsRequire = import.meta.url
+  ? createRequire(import.meta.url)
+  : /* istanbul ignore next */ require
 
 export const { name, version } = cjsRequire<{ name: string; version: string }>(
   '../package.json',

src/rules/no-deprecated.ts

@@ -1,5 +1,5 @@
 import type { TSESTree } from '@typescript-eslint/utils'
-import type { Tag } from 'doctrine'
+import type { Spec } from 'comment-parser'
 
 import type { ModuleNamespace } from '../utils/index.js'
 import {
@@ -9,7 +9,7 @@ import {
   getValue,
 } from '../utils/index.js'
 
-function message(deprecation: Tag) {
+function message(deprecation: Spec) {
   if (deprecation.description) {
     return {
       messageId: 'deprecatedDesc',
@@ -25,7 +25,7 @@ function getDeprecation(metadata?: ModuleNamespace | null) {
     return
   }
 
-  return metadata.doc.tags.find(t => t.title === 'deprecated')
+  return metadata.doc.tags.find(t => t.tag === 'deprecated')
 }
 
 export default createRule({
@@ -45,7 +45,7 @@ export default createRule({
   },
   defaultOptions: [],
   create(context) {
-    const deprecated = new Map<string, Tag>()
+    const deprecated = new Map<string, Spec>()
     const namespaces = new Map<string, ExportMap | null>()
 
     return {
@@ -66,7 +66,7 @@ export default createRule({
           }
 
           const moduleDeprecation = imports.doc?.tags.find(
-            t => t.title === 'deprecated',
+            t => t.tag === 'deprecated',
           )
           if (moduleDeprecation) {
             context.report({

src/utils/export-map.ts

@@ -2,9 +2,9 @@ import fs from 'node:fs'
 import path from 'node:path'
 
 import type { TSESLint, TSESTree } from '@typescript-eslint/utils'
+import { parse as parseComment_ } from 'comment-parser'
+import type { Block } from 'comment-parser'
 import debug from 'debug'
-import type { Annotation } from 'doctrine'
-import * as doctrine from 'doctrine'
 import type { AST } from 'eslint'
 import { SourceCode } from 'eslint'
 import type { TsConfigJsonResolved, TsConfigResult } from 'get-tsconfig'
@@ -36,7 +36,7 @@ const tsconfigCache = new Map<string, TsConfigJsonResolved | null | undefined>()
 
 export type DocStyleParsers = Record<
   DocStyle,
-  (comments: TSESTree.Comment[]) => Annotation | undefined
+  (comments: TSESTree.Comment[]) => Block | undefined
 >
 
 export interface DeclarationMetadata {
@@ -47,7 +47,7 @@ export interface DeclarationMetadata {
 }
 
 export interface ModuleNamespace {
-  doc?: Annotation
+  doc?: Block
   namespace?: ExportMap | null
 }
 
@@ -67,6 +67,26 @@ const declTypes = new Set([
   'TSModuleDeclaration',
 ])
 
+// https://github.com/syavorsky/comment-parser/issues/172
+const fixup = new Set(['deprecated', 'module'])
+
+const parseComment = (comment: string): Block => {
+  const restored = `/**${comment.split('\n').reduce((acc, line) => {
+    line = line.trim()
+    return line && line !== '*' ? acc + '\n  ' + line : acc
+  }, '')}
+  */`
+  const [doc] = parseComment_(restored)
+  return {
+    ...doc,
+    tags: doc.tags.map(t =>
+      t.name && fixup.has(t.tag)
+        ? { ...t, description: `${t.name} ${t.description}` }
+        : t,
+    ),
+  }
+}
+
 export class ExportMap {
   static for(context: ChildContext) {
     const filepath = context.path
@@ -663,20 +683,20 @@ export class ExportMap {
 
     // attempt to collect module doc
     defineLazyProperty(m, 'doc', () => {
-      if (ast.comments) {
-        for (let i = 0, len = ast.comments.length; i < len; i++) {
-          const c = ast.comments[i]
-          if (c.type !== 'Block') {
-            continue
-          }
-          try {
-            const doc = doctrine.parse(c.value, { unwrap: true })
-            if (doc.tags.some(t => t.title === 'module')) {
-              return doc
-            }
-          } catch {
-            /* ignore */
+      if (!ast.comments?.length) {
+        return
+      }
+      for (const c of ast.comments) {
+        if (c.type !== 'Block') {
+          continue
+        }
+        try {
+          const doc = parseComment(c.value)
+          if (doc.tags.some(t => t.tag === 'module')) {
+            return doc
           }
+        } catch {
+          /* ignore */
         }
       }
     })
@@ -727,7 +747,7 @@ export class ExportMap {
 
   declare private mtime: number
 
-  declare doc: Annotation | undefined
+  declare doc: Block | undefined
 
   constructor(public path: string) {}
 
@@ -943,7 +963,7 @@ function captureDoc(
   ...nodes: Array<TSESTree.Node | undefined>
 ) {
   const metadata: {
-    doc?: Annotation | undefined
+    doc?: Block | undefined
   } = {}
 
   defineLazyProperty(metadata, 'doc', () => {
@@ -1002,15 +1022,15 @@ function captureJsDoc(comments: TSESTree.Comment[]) {
       continue
     }
     try {
-      return doctrine.parse(comment.value, { unwrap: true })
+      return parseComment(comment.value)
     } catch {
       /* don't care, for now? maybe add to `errors?` */
     }
   }
 }
 
 /** Parse TomDoc section from comments */
-function captureTomDoc(comments: TSESTree.Comment[]): Annotation | undefined {
+function captureTomDoc(comments: TSESTree.Comment[]): Block | undefined {
   // collect lines up to first paragraph break
   const lines = []
   for (const comment of comments) {
@@ -1020,7 +1040,7 @@ function captureTomDoc(comments: TSESTree.Comment[]): Annotation | undefined {
     lines.push(comment.value.trim())
   }
 
-  // return doctrine-like object
+  // return comment-parser-like object
   const statusMatch = lines
     .join(' ')
     .match(/^(Public|Internal|Deprecated):\s*(.+)/)
@@ -1029,11 +1049,11 @@ function captureTomDoc(comments: TSESTree.Comment[]): Annotation | undefined {
       description: statusMatch[2],
       tags: [
         {
-          title: statusMatch[1].toLowerCase(),
+          tag: statusMatch[1].toLowerCase(),
           description: statusMatch[2],
         },
       ],
-    }
+    } as Block
   }
 }
 

src/utils/resolve.ts

@@ -18,10 +18,9 @@ import {
 } from './legacy-resolver-settings.js'
 import { ModuleCache } from './module-cache.js'
 
-const _filename =
-  typeof __filename === 'undefined'
-    ? fileURLToPath(import.meta.url)
-    : /* istanbul ignore next */ __filename
+const _filename = import.meta.url
+  ? fileURLToPath(import.meta.url)
+  : /* istanbul ignore next */ __filename
 const _dirname = path.dirname(_filename)
 
 export const CASE_SENSITIVE_FS = !fs.existsSync(

test/rules/no-extraneous-dependencies.spec.ts

@@ -109,7 +109,7 @@ ruleTester.run('no-extraneous-dependencies', rule, {
     }),
     tValid({ code: 'require(6)' }),
     tValid({
-      code: 'import "doctrine"',
+      code: 'import "comment-parser"',
       options: [{ packageDir: path.join(_dirname, '../../') }],
     }),
     tValid({

test/utils/export-map.spec.ts

@@ -31,10 +31,7 @@ function jsdocTests(parseContext: ChildContext, lineEnding: string) {
     it('works with named imports.', () => {
       expect(imports.has('fn')).toBe(true)
 
-      expect(imports.get('fn')).toHaveProperty(
-        'doc.tags[0].title',
-        'deprecated',
-      )
+      expect(imports.get('fn')).toHaveProperty('doc.tags[0].tag', 'deprecated')
       expect(imports.get('fn')).toHaveProperty(
         'doc.tags[0].description',
         "Please use 'x' instead.",
@@ -45,7 +42,7 @@ function jsdocTests(parseContext: ChildContext, lineEnding: string) {
       expect(imports.has('default')).toBe(true)
       const importMeta = imports.get('default')
 
-      expect(importMeta).toHaveProperty('doc.tags[0].title', 'deprecated')
+      expect(importMeta).toHaveProperty('doc.tags[0].tag', 'deprecated')
       expect(importMeta).toHaveProperty(
         'doc.tags[0].description',
         'This is awful, use NotAsBadClass.',
@@ -56,7 +53,7 @@ function jsdocTests(parseContext: ChildContext, lineEnding: string) {
       expect(imports.has('MY_TERRIBLE_ACTION')).toBe(true)
       const importMeta = imports.get('MY_TERRIBLE_ACTION')
 
-      expect(importMeta).toHaveProperty('doc.tags[0].title', 'deprecated')
+      expect(importMeta).toHaveProperty('doc.tags[0].tag', 'deprecated')
       expect(importMeta).toHaveProperty(
         'doc.tags[0].description',
         'Please stop sending/handling this action type.',
@@ -68,7 +65,7 @@ function jsdocTests(parseContext: ChildContext, lineEnding: string) {
         expect(imports.has('CHAIN_A')).toBe(true)
         const importMeta = imports.get('CHAIN_A')
 
-        expect(importMeta).toHaveProperty('doc.tags[0].title', 'deprecated')
+        expect(importMeta).toHaveProperty('doc.tags[0].tag', 'deprecated')
         expect(importMeta).toHaveProperty(
           'doc.tags[0].description',
           'This chain is awful',
@@ -78,14 +75,14 @@ function jsdocTests(parseContext: ChildContext, lineEnding: string) {
         expect(imports.has('CHAIN_B')).toBe(true)
         const importMeta = imports.get('CHAIN_B')
 
-        expect(importMeta).toHaveProperty('doc.tags[0].title', 'deprecated')
+        expect(importMeta).toHaveProperty('doc.tags[0].tag', 'deprecated')
         expect(importMeta).toHaveProperty('doc.tags[0].description', 'So awful')
       })
       it('works for the third one, etc.', () => {
         expect(imports.has('CHAIN_C')).toBe(true)
         const importMeta = imports.get('CHAIN_C')
 
-        expect(importMeta).toHaveProperty('doc.tags[0].title', 'deprecated')
+        expect(importMeta).toHaveProperty('doc.tags[0].tag', 'deprecated')
         expect(importMeta).toHaveProperty(
           'doc.tags[0].description',
           'Still terrible',