eslint-plugin-jsdoc 65.3.16 → 65.4.0
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 +1 -1
- package/src/rules/checkTagNames.js +373 -0
package/package.json
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
1
|
import iterateJsdoc from '../iterateJsdoc.js';
|
|
2
|
+
import {
|
|
3
|
+
stringify as stringifyComment,
|
|
4
|
+
} from 'comment-parser';
|
|
2
5
|
import escapeStringRegexp from 'escape-string-regexp';
|
|
3
6
|
|
|
4
7
|
// https://babeljs.io/docs/en/babel-plugin-transform-react-jsx/
|
|
@@ -43,6 +46,133 @@ const isClassMember = (node) => {
|
|
|
43
46
|
return node?.parent?.type === 'ClassBody';
|
|
44
47
|
};
|
|
45
48
|
|
|
49
|
+
/**
|
|
50
|
+
* @param {import('@typescript-eslint/types').TSESTree.Node} member
|
|
51
|
+
* @returns {string|undefined}
|
|
52
|
+
*/
|
|
53
|
+
const getObjectMemberName = (member) => {
|
|
54
|
+
if (member.type !== 'Property' && member.type !== 'TSPropertySignature') {
|
|
55
|
+
return undefined;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const typedMember = /** @type {import('@typescript-eslint/types').TSESTree.Property|import('@typescript-eslint/types').TSESTree.TSPropertySignature} */ (
|
|
59
|
+
member
|
|
60
|
+
);
|
|
61
|
+
if (typedMember.computed && typedMember.key.type !== 'Literal') {
|
|
62
|
+
return undefined;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const {
|
|
66
|
+
key,
|
|
67
|
+
} = typedMember;
|
|
68
|
+
if (key.type === 'Identifier') {
|
|
69
|
+
return key.name;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
if (key.type === 'Literal' && typeof key.value === 'string') {
|
|
73
|
+
return key.value;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
return undefined;
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* @param {import('@typescript-eslint/types').TSESTree.Node[]} members
|
|
81
|
+
* @returns {Map<string, import('eslint').Rule.Node>}
|
|
82
|
+
*/
|
|
83
|
+
const indexObjectMembers = (members) => {
|
|
84
|
+
/** @type {Map<string, import('eslint').Rule.Node>} */
|
|
85
|
+
const properties = new Map();
|
|
86
|
+
for (const member of members) {
|
|
87
|
+
const name = getObjectMemberName(member);
|
|
88
|
+
if (!name || properties.has(name)) {
|
|
89
|
+
continue;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
properties.set(name, /** @type {import('eslint').Rule.Node} */ (member));
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
return properties;
|
|
96
|
+
};
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Object expression or type literal whose properties can receive moved docs.
|
|
100
|
+
* Export wrappers are unwrapped so `export const X = { ... }` is recognized.
|
|
101
|
+
* @param {import('eslint').Rule.Node} node
|
|
102
|
+
* @returns {Map<string, import('eslint').Rule.Node>|null}
|
|
103
|
+
*/
|
|
104
|
+
const getAttachedObjectProperties = (node) => {
|
|
105
|
+
if (node.type === 'ExportNamedDeclaration') {
|
|
106
|
+
const exported = /** @type {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration} */ (
|
|
107
|
+
node
|
|
108
|
+
).declaration;
|
|
109
|
+
if (!exported) {
|
|
110
|
+
return null;
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
return getAttachedObjectProperties(/** @type {import('eslint').Rule.Node} */ (
|
|
114
|
+
exported
|
|
115
|
+
));
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
if (node.type !== 'VariableDeclaration') {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
const variableDeclaration = /** @type {import('@typescript-eslint/types').TSESTree.VariableDeclaration} */ (
|
|
123
|
+
node
|
|
124
|
+
);
|
|
125
|
+
const declarator = variableDeclaration.declarations[0];
|
|
126
|
+
|
|
127
|
+
/* c8 ignore next 3 -- `VariableDeclaration` always has a declarator. */
|
|
128
|
+
if (!declarator) {
|
|
129
|
+
return null;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
if (declarator.init?.type === 'ObjectExpression') {
|
|
133
|
+
return indexObjectMembers(declarator.init.properties);
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const typeAnnotation = declarator.id.type === 'Identifier' ?
|
|
137
|
+
declarator.id.typeAnnotation?.typeAnnotation :
|
|
138
|
+
undefined;
|
|
139
|
+
if (typeAnnotation?.type === 'TSTypeLiteral') {
|
|
140
|
+
return indexObjectMembers(typeAnnotation.members);
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
return null;
|
|
144
|
+
};
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Description text to move for `@prop NAME - description`, or `null` when
|
|
148
|
+
* the tag is not that shape. A leading hyphen is the JSDoc separator.
|
|
149
|
+
* @param {import('comment-parser').Spec} tag
|
|
150
|
+
* @returns {string|null}
|
|
151
|
+
*/
|
|
152
|
+
const getPropertyTagDescription = (tag) => {
|
|
153
|
+
if (!tag.name) {
|
|
154
|
+
return null;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/** @type {string[]} */
|
|
158
|
+
const lines = [];
|
|
159
|
+
for (const src of tag.source) {
|
|
160
|
+
if (src.tokens.end && !src.tokens.tag && !src.tokens.description) {
|
|
161
|
+
break;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
if (src.tokens.tag) {
|
|
165
|
+
lines.push(src.tokens.description.replace(/^\s*-\s*/v, ''));
|
|
166
|
+
continue;
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
lines.push(src.tokens.description);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
const description = lines.join('\n').trim();
|
|
173
|
+
return description || null;
|
|
174
|
+
};
|
|
175
|
+
|
|
46
176
|
const typedTagsUnnecessaryOutsideDeclare = new Set([
|
|
47
177
|
'abstract',
|
|
48
178
|
'access',
|
|
@@ -255,9 +385,252 @@ export default iterateJsdoc(({
|
|
|
255
385
|
return false;
|
|
256
386
|
};
|
|
257
387
|
|
|
388
|
+
/**
|
|
389
|
+
* @param {import('eslint').Rule.Node} propNode
|
|
390
|
+
* @returns {boolean}
|
|
391
|
+
*/
|
|
392
|
+
const propertyHasJsdoc = (propNode) => {
|
|
393
|
+
return sourceCode.getCommentsBefore(propNode).some((comment) => {
|
|
394
|
+
return comment.type === 'Block' && comment.value.startsWith('*');
|
|
395
|
+
});
|
|
396
|
+
};
|
|
397
|
+
|
|
398
|
+
/**
|
|
399
|
+
* @param {string} tagName
|
|
400
|
+
* @returns {boolean}
|
|
401
|
+
*/
|
|
402
|
+
const isRelocatablePropertyTag = (tagName) => {
|
|
403
|
+
return tagName === 'property' ||
|
|
404
|
+
tagName === 'prop' && !Object.hasOwn(tagNamePreference, 'prop');
|
|
405
|
+
};
|
|
406
|
+
|
|
407
|
+
/**
|
|
408
|
+
* @param {string} commentText
|
|
409
|
+
* @returns {boolean}
|
|
410
|
+
*/
|
|
411
|
+
const commentHasText = (commentText) => {
|
|
412
|
+
return commentText.split(/\r?\n/v).some((line) => {
|
|
413
|
+
return (/\S/v).test(line.replaceAll('*', '').replaceAll('/', ''));
|
|
414
|
+
});
|
|
415
|
+
};
|
|
416
|
+
|
|
417
|
+
/**
|
|
418
|
+
* @param {import('eslint').Rule.RuleFixer} fixer
|
|
419
|
+
* @returns {import('eslint').Rule.Fix}
|
|
420
|
+
*/
|
|
421
|
+
const removeJsdocFix = (fixer) => {
|
|
422
|
+
const text = sourceCode.text;
|
|
423
|
+
const lastLineBreakPos = text.slice(0, jsdocNode.range[0]).search(/\n[ \t]*$/v);
|
|
424
|
+
if (lastLineBreakPos > -1) {
|
|
425
|
+
return fixer.removeRange([
|
|
426
|
+
lastLineBreakPos, jsdocNode.range[1],
|
|
427
|
+
]);
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
return fixer.removeRange(
|
|
431
|
+
(/\s/v).test(text.charAt(jsdocNode.range[1])) ?
|
|
432
|
+
[
|
|
433
|
+
jsdocNode.range[0], jsdocNode.range[1] + 1,
|
|
434
|
+
] :
|
|
435
|
+
jsdocNode.range,
|
|
436
|
+
);
|
|
437
|
+
};
|
|
438
|
+
|
|
439
|
+
/**
|
|
440
|
+
* Same end state as the per-tag redundant-property fixer, but applied to
|
|
441
|
+
* every `@prop`/`@property` in this block at once. Doing them together
|
|
442
|
+
* avoids a later pass relocating whichever names still remain.
|
|
443
|
+
* @param {import('comment-parser').Spec[]} tags
|
|
444
|
+
* @returns {string}
|
|
445
|
+
*/
|
|
446
|
+
const stripPropertyTags = (tags) => {
|
|
447
|
+
/** @type {Set<number>} */
|
|
448
|
+
const clearTagLine = new Set();
|
|
449
|
+
/** @type {Set<number>} */
|
|
450
|
+
const dropLines = new Set();
|
|
451
|
+
for (const tag of tags) {
|
|
452
|
+
if (tag.description.trim()) {
|
|
453
|
+
clearTagLine.add(tag.source[0].number);
|
|
454
|
+
continue;
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
for (const src of tag.source) {
|
|
458
|
+
if (src.tokens.end && !src.tokens.tag) {
|
|
459
|
+
break;
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
dropLines.add(src.number);
|
|
463
|
+
}
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
const cloned = structuredClone(jsdoc);
|
|
467
|
+
cloned.source = cloned.source.flatMap((line) => {
|
|
468
|
+
if (dropLines.has(line.number)) {
|
|
469
|
+
return [];
|
|
470
|
+
}
|
|
471
|
+
|
|
472
|
+
if (!clearTagLine.has(line.number)) {
|
|
473
|
+
return [
|
|
474
|
+
line,
|
|
475
|
+
];
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
return [
|
|
479
|
+
{
|
|
480
|
+
...line,
|
|
481
|
+
tokens: {
|
|
482
|
+
...line.tokens,
|
|
483
|
+
postTag: '',
|
|
484
|
+
postType: '',
|
|
485
|
+
tag: '',
|
|
486
|
+
type: '',
|
|
487
|
+
},
|
|
488
|
+
},
|
|
489
|
+
];
|
|
490
|
+
});
|
|
491
|
+
|
|
492
|
+
const stripped = stringifyComment(cloned);
|
|
493
|
+
return commentHasText(stripped) ? stripped : '';
|
|
494
|
+
};
|
|
495
|
+
|
|
496
|
+
/**
|
|
497
|
+
* Relocate every redundant `@prop`/`@property` description onto a matching
|
|
498
|
+
* property, or strip those tags in one step when the object is recognized
|
|
499
|
+
* but not every tag can be moved.
|
|
500
|
+
* @returns {import('eslint').Rule.ReportFixer|null}
|
|
501
|
+
*/
|
|
502
|
+
const getPropertyRelocationFixer = () => {
|
|
503
|
+
if (!typed || !enableFixer || !node) {
|
|
504
|
+
return null;
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
const properties = getAttachedObjectProperties(node);
|
|
508
|
+
if (!properties) {
|
|
509
|
+
return null;
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
/** @type {import('comment-parser').Spec[]} */
|
|
513
|
+
const propertyTags = jsdoc.tags.filter((jsdocTag) => {
|
|
514
|
+
return isRelocatablePropertyTag(jsdocTag.tag);
|
|
515
|
+
});
|
|
516
|
+
if (!propertyTags.length) {
|
|
517
|
+
return null;
|
|
518
|
+
}
|
|
519
|
+
|
|
520
|
+
/**
|
|
521
|
+
* @type {{
|
|
522
|
+
* description: string,
|
|
523
|
+
* prop: import('eslint').Rule.Node,
|
|
524
|
+
* tag: import('comment-parser').Spec
|
|
525
|
+
* }[]}
|
|
526
|
+
*/
|
|
527
|
+
const moves = [];
|
|
528
|
+
/** @type {Set<string>} */
|
|
529
|
+
const seenNames = new Set();
|
|
530
|
+
let canRelocate = true;
|
|
531
|
+
for (const jsdocTag of propertyTags) {
|
|
532
|
+
const description = getPropertyTagDescription(jsdocTag);
|
|
533
|
+
const prop = description ? properties.get(jsdocTag.name) : undefined;
|
|
534
|
+
if (!description || !prop || propertyHasJsdoc(prop) || seenNames.has(jsdocTag.name)) {
|
|
535
|
+
canRelocate = false;
|
|
536
|
+
break;
|
|
537
|
+
}
|
|
538
|
+
|
|
539
|
+
seenNames.add(jsdocTag.name);
|
|
540
|
+
moves.push({
|
|
541
|
+
description,
|
|
542
|
+
prop,
|
|
543
|
+
tag: jsdocTag,
|
|
544
|
+
});
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
if (!canRelocate) {
|
|
548
|
+
const stripped = stripPropertyTags(propertyTags);
|
|
549
|
+
return (fixer) => {
|
|
550
|
+
return stripped ? fixer.replaceText(jsdocNode, stripped) : removeJsdocFix(fixer);
|
|
551
|
+
};
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
return (fixer) => {
|
|
555
|
+
/** @type {import('eslint').Rule.Fix[]} */
|
|
556
|
+
const fixes = [];
|
|
557
|
+
const lineBreak = sourceCode.text.includes('\r\n') ? '\r\n' : '\n';
|
|
558
|
+
const commentText = sourceCode.getText(jsdocNode);
|
|
559
|
+
const commentLines = commentText.split(/\r?\n/v);
|
|
560
|
+
/** @type {Set<number>} */
|
|
561
|
+
const removeOffsets = new Set();
|
|
562
|
+
for (const move of moves) {
|
|
563
|
+
const srcLines = move.tag.source;
|
|
564
|
+
removeOffsets.add(srcLines[0].number);
|
|
565
|
+
for (const line of srcLines.slice(1)) {
|
|
566
|
+
if (line.tokens.tag || line.tokens.end) {
|
|
567
|
+
break;
|
|
568
|
+
}
|
|
569
|
+
|
|
570
|
+
removeOffsets.add(line.number);
|
|
571
|
+
}
|
|
572
|
+
}
|
|
573
|
+
|
|
574
|
+
const kept = commentLines.filter((_, idx) => {
|
|
575
|
+
return !removeOffsets.has(idx);
|
|
576
|
+
});
|
|
577
|
+
if (commentHasText(kept.join('\n'))) {
|
|
578
|
+
let nextLines = kept;
|
|
579
|
+
const indent = /** @type {RegExpExecArray} */ (
|
|
580
|
+
(/^[ \t]*/v).exec(/** @type {string} */ (commentLines[0]))
|
|
581
|
+
)[0];
|
|
582
|
+
if (!nextLines.some((line) => {
|
|
583
|
+
return line.includes('/**');
|
|
584
|
+
})) {
|
|
585
|
+
nextLines = [
|
|
586
|
+
`${indent}/**`, ...nextLines,
|
|
587
|
+
];
|
|
588
|
+
}
|
|
589
|
+
|
|
590
|
+
if (!nextLines.at(-1)?.includes('*/')) {
|
|
591
|
+
nextLines = [
|
|
592
|
+
...nextLines, `${indent} */`,
|
|
593
|
+
];
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
fixes.push(fixer.replaceText(jsdocNode, nextLines.join(lineBreak)));
|
|
597
|
+
} else {
|
|
598
|
+
fixes.push(removeJsdocFix(fixer));
|
|
599
|
+
}
|
|
600
|
+
|
|
601
|
+
for (const move of moves) {
|
|
602
|
+
const propLine = /** @type {string} */ (sourceCode.lines[
|
|
603
|
+
/** @type {import('eslint').AST.SourceLocation} */
|
|
604
|
+
(move.prop.loc).start.line - 1
|
|
605
|
+
]);
|
|
606
|
+
const indent = /** @type {RegExpExecArray} */ (
|
|
607
|
+
(/^[ \t]*/v).exec(propLine)
|
|
608
|
+
)[0];
|
|
609
|
+
const descriptionLines = move.description.split('\n');
|
|
610
|
+
const insertion = `/**${lineBreak}${descriptionLines.map((line) => {
|
|
611
|
+
return `${indent} *${line ? ` ${line}` : ''}`;
|
|
612
|
+
}).join(lineBreak)}${lineBreak}${indent} */${lineBreak}${indent}`;
|
|
613
|
+
fixes.push(fixer.insertTextBefore(move.prop, insertion));
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
return fixes;
|
|
617
|
+
};
|
|
618
|
+
};
|
|
619
|
+
|
|
620
|
+
const propertyRelocationFixer = getPropertyRelocationFixer();
|
|
621
|
+
|
|
258
622
|
for (let tagIndex = 0; tagIndex < jsdoc.tags.length; tagIndex += 1) {
|
|
259
623
|
const jsdocTag = jsdoc.tags[tagIndex];
|
|
260
624
|
const tagName = jsdocTag.tag;
|
|
625
|
+
|
|
626
|
+
if (propertyRelocationFixer && isRelocatablePropertyTag(tagName)) {
|
|
627
|
+
const message = tagName === 'property' ?
|
|
628
|
+
`'@${tagName}' is redundant when using a type system.` :
|
|
629
|
+
`Invalid JSDoc tag (preference). Replace "${tagName}" JSDoc tag with "property".`;
|
|
630
|
+
report(message, propertyRelocationFixer, jsdocTag);
|
|
631
|
+
continue;
|
|
632
|
+
}
|
|
633
|
+
|
|
261
634
|
if (jsxTags && jsxTagNames.has(tagName)) {
|
|
262
635
|
continue;
|
|
263
636
|
}
|