eslint-plugin-jsdoc 65.3.14 → 65.3.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -5,9 +5,10 @@
5
5
  "url": "http://gajus.com"
6
6
  },
7
7
  "dependencies": {
8
- "@es-joy/jsdoccomment": "~0.98.0",
8
+ "@es-joy/escodegen": "^4.2.0",
9
+ "@es-joy/jsdoccomment": "~0.100.0",
9
10
  "@es-joy/resolve.exports": "1.2.0",
10
- "@typescript-eslint/utils": "^8.70.1",
11
+ "@typescript-eslint/utils": "^8.72.0",
11
12
  "are-docs-informative": "^0.1.1",
12
13
  "comment-parser": "1.4.9",
13
14
  "debug": "^4.4.3",
@@ -24,11 +25,10 @@
24
25
  "description": "JSDoc linting rules for ESLint.",
25
26
  "devDependencies": {
26
27
  "@arethetypeswrong/cli": "^0.18.5",
27
- "@babel/core": "8.0.6",
28
- "@babel/eslint-parser": "8.0.5",
28
+ "@babel/core": "8.0.7",
29
+ "@babel/eslint-parser": "8.0.7",
29
30
  "@babel/plugin-transform-flow-strip-types": "8.0.1",
30
- "@babel/preset-env": "8.0.6",
31
- "@es-joy/escodegen": "^4.2.0",
31
+ "@babel/preset-env": "8.0.7",
32
32
  "@es-joy/jsdoc-eslint-parser": "^0.29.0",
33
33
  "@eslint/core": "^1.2.1",
34
34
  "@hkdobrev/run-if-changed": "^0.9.0",
@@ -41,36 +41,36 @@
41
41
  "@types/estree": "^1.0.9",
42
42
  "@types/json-schema": "^7.0.15",
43
43
  "@types/mocha": "^10.0.10",
44
- "@types/node": "^26.6.2",
44
+ "@types/node": "^26.6.5",
45
45
  "@types/semver": "^7.8.0",
46
46
  "@types/spdx-expression-parse": "^4.0.0",
47
- "@typescript-eslint/types": "8.70.1",
47
+ "@typescript-eslint/types": "8.72.0",
48
48
  "babel-plugin-add-module-exports": "^1.0.4",
49
- "babel-plugin-transform-import-meta": "^3.0.0",
49
+ "babel-plugin-transform-import-meta": "^3.1.0",
50
50
  "c8": "^12.0.0",
51
- "camelcase": "^9.0.0",
52
- "chai": "^6.2.2",
53
- "decamelize": "^6.0.1",
54
- "eslint": "10.11.0",
51
+ "camelcase": "^10.0.0",
52
+ "chai": "^6.3.0",
53
+ "decamelize": "^7.0.0",
54
+ "eslint": "10.13.0",
55
55
  "eslint-config-canonical": "^47.4.2",
56
56
  "gitdown": "^4.1.1",
57
57
  "glob": "^13.0.6",
58
- "globals": "^17.12.0",
58
+ "globals": "^17.13.0",
59
59
  "husky": "^9.1.7",
60
- "jsdoc-type-pratt-parser": "^9.2.2",
60
+ "jsdoc-type-pratt-parser": "^9.3.0",
61
61
  "json-schema": "^0.4.0",
62
62
  "json-schema-to-typescript": "^16.0.0",
63
- "lint-staged": "^17.5.1",
64
- "mocha": "^12.0.2",
63
+ "lint-staged": "^17.6.0",
64
+ "mocha": "^12.0.3",
65
65
  "open-editor": "^6.0.0",
66
- "playwright": "^1.63.0",
66
+ "playwright": "^1.64.1",
67
67
  "replace": "^1.2.2",
68
68
  "rimraf": "^6.1.3",
69
69
  "semantic-release": "^25.0.9",
70
70
  "sinon": "^22.1.0",
71
71
  "ts-api-utils": "^2.5.0",
72
72
  "typescript": "6.0.3",
73
- "typescript-eslint": "8.70.1"
73
+ "typescript-eslint": "8.72.0"
74
74
  },
75
75
  "engines": {
76
76
  "node": "^22.22.2 || >=24.15.0"
@@ -163,5 +163,5 @@
163
163
  "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
164
164
  "test-index": "pnpm run test-no-cov test/rules/index.js"
165
165
  },
166
- "version": "65.3.14"
166
+ "version": "65.3.16"
167
167
  }
@@ -1,10 +1,16 @@
1
1
  import iterateJsdoc from './iterateJsdoc.js';
2
+ import {
3
+ generate,
4
+ } from '@es-joy/escodegen';
2
5
  import {
3
6
  parse,
4
7
  stringify,
5
8
  traverse,
6
9
  tryParse,
7
10
  } from '@es-joy/jsdoccomment';
11
+ import {
12
+ parse as espree,
13
+ } from 'espree';
8
14
 
9
15
  /**
10
16
  * Adjusts the parent type node `meta` for generic matches (or type node
@@ -380,7 +386,13 @@ export const buildRejectOrPreferRuleDefinition = ({
380
386
  let typeAst;
381
387
 
382
388
  try {
383
- typeAst = mode === 'permissive' ? tryParse(jsdocTag.type) : parse(jsdocTag.type, mode);
389
+ typeAst = mode === 'permissive' ?
390
+ tryParse(jsdocTag.type, undefined, {
391
+ computedPropertyParser: espree,
392
+ }) :
393
+ parse(jsdocTag.type, mode, {
394
+ computedPropertyParser: espree,
395
+ });
384
396
  } catch {
385
397
  continue;
386
398
  }
@@ -408,7 +420,7 @@ export const buildRejectOrPreferRuleDefinition = ({
408
420
  });
409
421
 
410
422
  if (invalidTypes.length) {
411
- const fixedType = stringify(typeAst);
423
+ const fixedType = stringify(typeAst, generate);
412
424
 
413
425
  /**
414
426
  * @type {import('eslint').Rule.ReportFixer}
package/src/jsdocUtils.js CHANGED
@@ -5,11 +5,17 @@ import {
5
5
  typeScriptTags,
6
6
  } from './tagNames.js';
7
7
  import WarnSettings from './WarnSettings.js';
8
+ import {
9
+ generate,
10
+ } from '@es-joy/escodegen';
8
11
  import {
9
12
  parseComment,
10
13
  stringify,
11
14
  tryParse,
12
15
  } from '@es-joy/jsdoccomment';
16
+ import {
17
+ parse as espree,
18
+ } from 'espree';
13
19
 
14
20
  /**
15
21
  * @typedef {number} Integer
@@ -971,6 +977,9 @@ const mayBeUndefinedTypeTag = (tag, mode) => {
971
977
  mode === 'permissive' ? undefined : [
972
978
  mode,
973
979
  ],
980
+ {
981
+ computedPropertyParser: espree,
982
+ },
974
983
  );
975
984
  } catch {
976
985
  // Ignore
@@ -2042,7 +2051,7 @@ const strictNativeTypes = [
2042
2051
  * @param {string} typeBracketSpacing
2043
2052
  */
2044
2053
  const rewireByParsedType = (jsdoc, tag, parsedType, indent, typeBracketSpacing = '') => {
2045
- const typeLines = stringify(parsedType).split('\n');
2054
+ const typeLines = stringify(parsedType, generate).split('\n');
2046
2055
  const firstTypeLine = typeLines.shift();
2047
2056
  const lastTypeLine = typeLines.pop();
2048
2057
 
@@ -11,6 +11,9 @@ import {
11
11
  traverse,
12
12
  tryParse as tryParseType,
13
13
  } from '@es-joy/jsdoccomment';
14
+ import {
15
+ parse as espree,
16
+ } from 'espree';
14
17
 
15
18
  export default iterateJsdoc(({
16
19
  jsdoc,
@@ -41,8 +44,12 @@ export default iterateJsdoc(({
41
44
  let parsedType;
42
45
  try {
43
46
  parsedType = mode === 'permissive' ?
44
- tryParseType(/** @type {string} */ (potentialType)) :
45
- parseType(/** @type {string} */ (potentialType), mode);
47
+ tryParseType(/** @type {string} */ (potentialType), undefined, {
48
+ computedPropertyParser: espree,
49
+ }) :
50
+ parseType(/** @type {string} */ (potentialType), mode, {
51
+ computedPropertyParser: espree,
52
+ });
46
53
  } catch {
47
54
  return;
48
55
  }
@@ -5,6 +5,9 @@ import {
5
5
  tryParse,
6
6
  } from '@es-joy/jsdoccomment';
7
7
  import * as resolve from '@es-joy/resolve.exports';
8
+ import {
9
+ parse as espree,
10
+ } from 'espree';
8
11
  import {
9
12
  readFileSync,
10
13
  } from 'node:fs';
@@ -69,7 +72,13 @@ export default iterateJsdoc(({
69
72
  for (const tag of jsdoc.tags) {
70
73
  let typeAst;
71
74
  try {
72
- typeAst = mode === 'permissive' ? tryParse(tag.type) : parse(tag.type, mode);
75
+ typeAst = mode === 'permissive' ?
76
+ tryParse(tag.type, undefined, {
77
+ computedPropertyParser: espree,
78
+ }) :
79
+ parse(tag.type, mode, {
80
+ computedPropertyParser: espree,
81
+ });
73
82
  } catch {
74
83
  continue;
75
84
  }
@@ -11,6 +11,9 @@ import {
11
11
  traverse,
12
12
  tryParse as tryParseType,
13
13
  } from '@es-joy/jsdoccomment';
14
+ import {
15
+ parse as espree,
16
+ } from 'espree';
14
17
  import {
15
18
  parseImportsExports,
16
19
  } from 'parse-imports-exports';
@@ -805,8 +808,12 @@ export default iterateJsdoc(({
805
808
  ];
806
809
  return {
807
810
  parsedType: mode === 'permissive' ?
808
- tryParseType(/** @type {string} */ (potentialType)) :
809
- parseType(/** @type {string} */ (potentialType), mode),
811
+ tryParseType(/** @type {string} */ (potentialType), undefined, {
812
+ computedPropertyParser: espree,
813
+ }) :
814
+ parseType(/** @type {string} */ (potentialType), mode, {
815
+ computedPropertyParser: espree,
816
+ }),
810
817
  tag,
811
818
  };
812
819
  } catch {
@@ -1,6 +1,9 @@
1
1
  import iterateJsdoc, {
2
2
  parseComment,
3
3
  } from '../iterateJsdoc.js';
4
+ import {
5
+ generate,
6
+ } from '@es-joy/escodegen';
4
7
  import {
5
8
  commentParserToESTree,
6
9
  estreeToString,
@@ -13,6 +16,9 @@ import {
13
16
  import {
14
17
  Linter,
15
18
  } from 'eslint';
19
+ import {
20
+ parse as espree,
21
+ } from 'espree';
16
22
  import {
17
23
  parseImportsExports,
18
24
  } from 'parse-imports-exports';
@@ -44,16 +50,26 @@ export default iterateJsdoc(({
44
50
  })
45
51
  .map((commentNode) => {
46
52
  return commentParserToESTree(
47
- parseComment(commentNode, ''), mode === 'permissive' ? 'typescript' : mode,
53
+ parseComment(commentNode, ''),
54
+ mode === 'permissive' ? 'typescript' : mode,
55
+ {
56
+ jsdocTypePrattParserArgs: {
57
+ // Pass it for parity, but probably not needed
58
+ // with the typedefs and import statements below
59
+ computedPropertyParser: espree,
60
+ },
61
+ },
48
62
  );
49
63
  });
50
64
 
65
+ // Only `@typedef` names are type aliases; names of `@param`,
66
+ // `@property`, `@const`, etc. are not types
51
67
  const typedefs = comments
52
68
  .flatMap((doc) => {
53
69
  return doc.tags.filter(({
54
70
  tag,
55
71
  }) => {
56
- return utils.isNameOrNamepathDefiningTag(tag);
72
+ return tag === 'typedef';
57
73
  });
58
74
  });
59
75
 
@@ -143,8 +159,12 @@ export default iterateJsdoc(({
143
159
  let parsedType;
144
160
  try {
145
161
  parsedType = mode === 'permissive' ?
146
- tryParseType(/** @type {string} */ (potentialType)) :
147
- parseType(/** @type {string} */ (potentialType), mode);
162
+ tryParseType(/** @type {string} */ (potentialType), undefined, {
163
+ computedPropertyParser: espree,
164
+ }) :
165
+ parseType(/** @type {string} */ (potentialType), mode, {
166
+ computedPropertyParser: espree,
167
+ });
148
168
  } catch {
149
169
  return;
150
170
  }
@@ -191,7 +211,7 @@ export default iterateJsdoc(({
191
211
 
192
212
  pathSegments.unshift(
193
213
  currentNode.right.type === 'JsdocTypeIndexedAccessIndex' ?
194
- stringify(currentNode.right.right) :
214
+ stringify(currentNode.right.right, generate) :
195
215
  currentNode.right.value,
196
216
  );
197
217
  nodes.unshift(currentNode);
@@ -270,7 +290,7 @@ export default iterateJsdoc(({
270
290
 
271
291
  for (const src of tag.source) {
272
292
  if (src.tokens.type) {
273
- src.tokens.type = `{${stringify(parsedType)}}`;
293
+ src.tokens.type = `{${stringify(parsedType, generate)}}`;
274
294
  break;
275
295
  }
276
296
  }
@@ -301,7 +321,7 @@ export default iterateJsdoc(({
301
321
 
302
322
  if (
303
323
  (typedefNode.right.type === 'JsdocTypeIndexedAccessIndex' &&
304
- stringify(typedefNode.right.right) !== pathSegment) ||
324
+ stringify(typedefNode.right.right, generate) !== pathSegment) ||
305
325
  (typedefNode.right.type !== 'JsdocTypeIndexedAccessIndex' &&
306
326
  typedefNode.right.value !== pathSegment)
307
327
  ) {
@@ -349,7 +369,9 @@ export default iterateJsdoc(({
349
369
  const findMatchingImport = () => {
350
370
  for (const imprt of imports) {
351
371
  const parsedImport = parseImportsExports(
352
- estreeToString(imprt).replace(/^\s*@/v, '').trim(),
372
+ estreeToString(imprt, {
373
+ jtppStringificationRules: generate,
374
+ }).replace(/^\s*@/v, '').trim(),
353
375
  );
354
376
 
355
377
  const namedImportsModuleSpecifier = Object.keys(parsedImport.namedImports || {})[0];
@@ -489,7 +511,9 @@ export default iterateJsdoc(({
489
511
  for (const tag of jsdoc.tags) {
490
512
  const mightHaveTypePosition = utils.tagMightHaveTypePosition(tag.tag);
491
513
  const hasTypePosition = mightHaveTypePosition === true && Boolean(tag.type);
492
- if (hasTypePosition && (!exemptTypedefs || !utils.isNameOrNamepathDefiningTag(tag.tag))) {
514
+ // Only the `@typedef` itself is exempt; `@param`, `@property`, `@const`,
515
+ // etc. are not type aliases and their `import()` types are reported
516
+ if (hasTypePosition && (!exemptTypedefs || tag.tag !== 'typedef')) {
493
517
  iterateInlineImports(tag);
494
518
  }
495
519
  }
@@ -7,6 +7,9 @@ import {
7
7
  traverse,
8
8
  tryParse as tryParseType,
9
9
  } from '@es-joy/jsdoccomment';
10
+ import {
11
+ parse as espree,
12
+ } from 'espree';
10
13
 
11
14
  /**
12
15
  * @type {Partial<Record<import('../jsdocUtils.js').ParserMode, import('jsdoc-type-pratt-parser').ParseMode[]>>}
@@ -152,7 +155,9 @@ export default iterateJsdoc(({
152
155
  const returnType = returnTag.type.trim();
153
156
  let parsedType;
154
157
  try {
155
- parsedType = tryParseType(returnType, parseTypeModes[parseMode]);
158
+ parsedType = tryParseType(returnType, parseTypeModes[parseMode], {
159
+ computedPropertyParser: espree,
160
+ });
156
161
  } catch {
157
162
  return false;
158
163
  }
@@ -4,6 +4,9 @@ import {
4
4
  traverse,
5
5
  tryParse as tryParseType,
6
6
  } from '@es-joy/jsdoccomment';
7
+ import {
8
+ parse as espree,
9
+ } from 'espree';
7
10
 
8
11
  export default iterateJsdoc(({
9
12
  context,
@@ -128,8 +131,12 @@ export default iterateJsdoc(({
128
131
  let parsedType;
129
132
  try {
130
133
  parsedType = mode === 'permissive' ?
131
- tryParseType(/** @type {string} */ (potentialTag.type)) :
132
- parseType(/** @type {string} */ (potentialTag.type), mode);
134
+ tryParseType(/** @type {string} */ (potentialTag.type), undefined, {
135
+ computedPropertyParser: espree,
136
+ }) :
137
+ parseType(/** @type {string} */ (potentialTag.type), mode, {
138
+ computedPropertyParser: espree,
139
+ });
133
140
  } catch {
134
141
  return;
135
142
  }
@@ -6,6 +6,9 @@ import {
6
6
  parse as parseType,
7
7
  traverse,
8
8
  } from '@es-joy/jsdoccomment';
9
+ import {
10
+ parse as espree,
11
+ } from 'espree';
9
12
 
10
13
  export default iterateJsdoc(({
11
14
  context,
@@ -26,7 +29,11 @@ export default iterateJsdoc(({
26
29
  let parsedType;
27
30
  try {
28
31
  parsedType = parseType(
29
- /** @type {string} */ (potentialType), 'typescript',
32
+ /** @type {string} */ (potentialType),
33
+ 'typescript',
34
+ {
35
+ computedPropertyParser: espree,
36
+ },
30
37
  );
31
38
  } catch {
32
39
  return;
@@ -3,6 +3,9 @@ import {
3
3
  parse as parseType,
4
4
  traverse,
5
5
  } from '@es-joy/jsdoccomment';
6
+ import {
7
+ parse as espree,
8
+ } from 'espree';
6
9
 
7
10
  export default iterateJsdoc(({
8
11
  settings,
@@ -20,7 +23,11 @@ export default iterateJsdoc(({
20
23
  let parsedType;
21
24
  try {
22
25
  parsedType = parseType(
23
- /** @type {string} */ (potentialType), 'typescript',
26
+ /** @type {string} */ (potentialType),
27
+ 'typescript',
28
+ {
29
+ computedPropertyParser: espree,
30
+ },
24
31
  );
25
32
  } catch {
26
33
  return;
@@ -6,6 +6,9 @@ import {
6
6
  parse as parseType,
7
7
  traverse,
8
8
  } from '@es-joy/jsdoccomment';
9
+ import {
10
+ parse as espree,
11
+ } from 'espree';
9
12
 
10
13
  export default iterateJsdoc(({
11
14
  context,
@@ -31,7 +34,11 @@ export default iterateJsdoc(({
31
34
  let parsedType;
32
35
  try {
33
36
  parsedType = parseType(
34
- /** @type {string} */ (potentialType), 'typescript',
37
+ /** @type {string} */ (potentialType),
38
+ 'typescript',
39
+ {
40
+ computedPropertyParser: espree,
41
+ },
35
42
  );
36
43
  } catch {
37
44
  return;
@@ -6,6 +6,9 @@ import {
6
6
  parse as parseType,
7
7
  traverse,
8
8
  } from '@es-joy/jsdoccomment';
9
+ import {
10
+ parse as espree,
11
+ } from 'espree';
9
12
 
10
13
  export default iterateJsdoc(({
11
14
  context,
@@ -27,7 +30,11 @@ export default iterateJsdoc(({
27
30
  let parsedType;
28
31
  try {
29
32
  parsedType = parseType(
30
- /** @type {string} */ (potentialType), 'typescript',
33
+ /** @type {string} */ (potentialType),
34
+ 'typescript',
35
+ {
36
+ computedPropertyParser: espree,
37
+ },
31
38
  );
32
39
  } catch {
33
40
  return;
@@ -2,12 +2,18 @@ import iterateJsdoc from '../iterateJsdoc.js';
2
2
  import {
3
3
  rewireByParsedType,
4
4
  } from '../jsdocUtils.js';
5
+ import {
6
+ generate,
7
+ } from '@es-joy/escodegen';
5
8
  import {
6
9
  parse as parseType,
7
10
  stringify,
8
11
  traverse,
9
12
  tryParse as tryParseType,
10
13
  } from '@es-joy/jsdoccomment';
14
+ import {
15
+ parse as espree,
16
+ } from 'espree';
11
17
 
12
18
  const digitRegex = (/^(\d+(\.\d*)?|\.\d+)([eE][\-+]?\d+)?$/v);
13
19
 
@@ -65,8 +71,12 @@ export default iterateJsdoc(({
65
71
  let parsedType;
66
72
  try {
67
73
  parsedType = mode === 'permissive' ?
68
- tryParseType(/** @type {string} */ (potentialType)) :
69
- parseType(/** @type {string} */ (potentialType), mode);
74
+ tryParseType(/** @type {string} */ (potentialType), undefined, {
75
+ computedPropertyParser: espree,
76
+ }) :
77
+ parseType(/** @type {string} */ (potentialType), mode, {
78
+ computedPropertyParser: espree,
79
+ });
70
80
  } catch {
71
81
  return;
72
82
  }
@@ -342,9 +352,9 @@ export default iterateJsdoc(({
342
352
  /* c8 ignore next 5 -- jsdoc-type-pratt-parser doesn't encode as should */
343
353
  ((typeNode.meta.trailingPunctuation ?? false) !== objectFieldSeparatorTrailingPunctuation &&
344
354
  ((typeNode.meta.trailingPunctuation && (!trailingPunctuationMultilineOnly ||
345
- !stringify(typeNode).includes('\n'))) ||
355
+ !stringify(typeNode, generate).includes('\n'))) ||
346
356
  (!typeNode.meta.trailingPunctuation && (!trailingPunctuationMultilineOnly ||
347
- stringify(typeNode).includes('\n')))))
357
+ stringify(typeNode, generate).includes('\n')))))
348
358
  ) {
349
359
  typeNode.meta.separator = objectFieldSeparatorOptionalLinebreak && !separator.endsWith('and-linebreak') ?
350
360
  objectFieldSeparator.replace(/-and-linebreak$/v, '') :
@@ -465,7 +475,7 @@ export default iterateJsdoc(({
465
475
  });
466
476
 
467
477
  const differentResult = tag.type !==
468
- typeBracketSpacing + stringify(parsedType) + typeBracketSpacing;
478
+ typeBracketSpacing + stringify(parsedType, generate) + typeBracketSpacing;
469
479
 
470
480
  if (errorMessages.length && differentResult) {
471
481
  for (const errorMessage of errorMessages) {
@@ -6,6 +6,9 @@ import {
6
6
  traverse,
7
7
  tryParse,
8
8
  } from '@es-joy/jsdoccomment';
9
+ import {
10
+ parse as espree,
11
+ } from 'espree';
9
12
 
10
13
  const inlineTags = new Set([
11
14
  // Typdoc
@@ -219,10 +222,12 @@ export default iterateJsdoc(({
219
222
  if (mode === 'permissive') {
220
223
  parsedTypes = tryParse(type, undefined, {
221
224
  classContext: true,
225
+ computedPropertyParser: espree,
222
226
  });
223
227
  } else {
224
228
  parsedTypes = parse(type, mode, {
225
229
  classContext: true,
230
+ computedPropertyParser: espree,
226
231
  });
227
232
  }
228
233
  } catch {
@@ -293,6 +298,7 @@ export default iterateJsdoc(({
293
298
  let parsedTypes;
294
299
 
295
300
  try {
301
+ // We don't need the second arg. for `closure` mode
296
302
  parsedTypes = tryParse(tag.type);
297
303
  } catch {
298
304
  // Ignore