eslint-plugin-jsdoc 56.0.0 → 56.0.2
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/dist/cjs/getJsdocProcessorPlugin.d.cts +5 -1
- package/dist/cjs/iterateJsdoc.d.cts +6 -2
- package/dist/getJsdocProcessorPlugin.cts +3 -1
- package/dist/iterateJsdoc.cts +9 -4
- package/package.json +4 -4
- package/src/getJsdocProcessorPlugin.cts +3 -1
- package/src/iterateJsdoc.cts +9 -4
- package/dist/cjs/WarnSettings.js +0 -30
- package/dist/cjs/alignTransform.js +0 -285
- package/dist/cjs/defaultTagOrder.js +0 -152
- package/dist/cjs/exportParser.js +0 -754
- package/dist/cjs/getDefaultTagStructureForMode.js +0 -840
- package/dist/cjs/getJsdocProcessorPlugin.cjs +0 -4
- package/dist/cjs/getJsdocProcessorPlugin.js +0 -553
- package/dist/cjs/index-cjs.js +0 -492
- package/dist/cjs/index.cjs.cjs +0 -6
- package/dist/cjs/iterateJsdoc.cjs +0 -38
- package/dist/cjs/iterateJsdoc.js +0 -1981
- package/dist/cjs/jsdocUtils.js +0 -1470
- package/dist/cjs/rules/checkAccess.js +0 -35
- package/dist/cjs/rules/checkAlignment.js +0 -63
- package/dist/cjs/rules/checkExamples.js +0 -486
- package/dist/cjs/rules/checkIndentation.js +0 -66
- package/dist/cjs/rules/checkLineAlignment.js +0 -297
- package/dist/cjs/rules/checkParamNames.js +0 -320
- package/dist/cjs/rules/checkPropertyNames.js +0 -105
- package/dist/cjs/rules/checkSyntax.js +0 -27
- package/dist/cjs/rules/checkTagNames.js +0 -252
- package/dist/cjs/rules/checkTemplateNames.js +0 -189
- package/dist/cjs/rules/checkTypes.js +0 -421
- package/dist/cjs/rules/checkValues.js +0 -163
- package/dist/cjs/rules/convertToJsdocComments.js +0 -313
- package/dist/cjs/rules/emptyTags.js +0 -79
- package/dist/cjs/rules/implementsOnClasses.js +0 -63
- package/dist/cjs/rules/importsAsDependencies.js +0 -105
- package/dist/cjs/rules/informativeDocs.js +0 -153
- package/dist/cjs/rules/linesBeforeBlock.js +0 -106
- package/dist/cjs/rules/matchDescription.js +0 -240
- package/dist/cjs/rules/matchName.js +0 -122
- package/dist/cjs/rules/multilineBlocks.js +0 -339
- package/dist/cjs/rules/noBadBlocks.js +0 -88
- package/dist/cjs/rules/noBlankBlockDescriptions.js +0 -56
- package/dist/cjs/rules/noBlankBlocks.js +0 -41
- package/dist/cjs/rules/noDefaults.js +0 -84
- package/dist/cjs/rules/noMissingSyntax.js +0 -164
- package/dist/cjs/rules/noMultiAsterisks.js +0 -83
- package/dist/cjs/rules/noRestrictedSyntax.js +0 -75
- package/dist/cjs/rules/noTypes.js +0 -88
- package/dist/cjs/rules/noUndefinedTypes.js +0 -451
- package/dist/cjs/rules/requireAsteriskPrefix.js +0 -144
- package/dist/cjs/rules/requireDescription.js +0 -136
- package/dist/cjs/rules/requireDescriptionCompleteSentence.js +0 -258
- package/dist/cjs/rules/requireExample.js +0 -103
- package/dist/cjs/rules/requireFileOverview.js +0 -117
- package/dist/cjs/rules/requireHyphenBeforeParamDescription.js +0 -144
- package/dist/cjs/rules/requireJsdoc.js +0 -629
- package/dist/cjs/rules/requireParam.js +0 -480
- package/dist/cjs/rules/requireParamDescription.js +0 -77
- package/dist/cjs/rules/requireParamName.js +0 -52
- package/dist/cjs/rules/requireParamType.js +0 -77
- package/dist/cjs/rules/requireProperty.js +0 -44
- package/dist/cjs/rules/requirePropertyDescription.js +0 -22
- package/dist/cjs/rules/requirePropertyName.js +0 -22
- package/dist/cjs/rules/requirePropertyType.js +0 -22
- package/dist/cjs/rules/requireReturns.js +0 -197
- package/dist/cjs/rules/requireReturnsCheck.js +0 -108
- package/dist/cjs/rules/requireReturnsDescription.js +0 -58
- package/dist/cjs/rules/requireReturnsType.js +0 -52
- package/dist/cjs/rules/requireTemplate.js +0 -173
- package/dist/cjs/rules/requireThrows.js +0 -101
- package/dist/cjs/rules/requireYields.js +0 -172
- package/dist/cjs/rules/requireYieldsCheck.js +0 -164
- package/dist/cjs/rules/sortTags.js +0 -392
- package/dist/cjs/rules/tagLines.js +0 -259
- package/dist/cjs/rules/textEscaping.js +0 -125
- package/dist/cjs/rules/typeFormatting.js +0 -328
- package/dist/cjs/rules/validTypes.js +0 -333
- package/dist/cjs/tagNames.js +0 -209
- package/dist/cjs/utils/hasReturnValue.js +0 -469
|
@@ -1,35 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
-
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
-
};
|
|
5
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
-
const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
|
|
7
|
-
const accessLevels = [
|
|
8
|
-
'package', 'private', 'protected', 'public',
|
|
9
|
-
];
|
|
10
|
-
exports.default = (0, iterateJsdoc_js_1.default)(({ report, utils, }) => {
|
|
11
|
-
utils.forEachPreferredTag('access', (jsdocParameter, targetTagName) => {
|
|
12
|
-
const desc = jsdocParameter.name + ' ' + jsdocParameter.description;
|
|
13
|
-
if (!accessLevels.includes(desc.trim())) {
|
|
14
|
-
report(`Missing valid JSDoc @${targetTagName} level.`, null, jsdocParameter);
|
|
15
|
-
}
|
|
16
|
-
});
|
|
17
|
-
const accessLength = utils.getTags('access').length;
|
|
18
|
-
const individualTagLength = utils.getPresentTags(accessLevels).length;
|
|
19
|
-
if (accessLength && individualTagLength) {
|
|
20
|
-
report('The @access tag may not be used with specific access-control tags (@package, @private, @protected, or @public).');
|
|
21
|
-
}
|
|
22
|
-
if (accessLength > 1 || individualTagLength > 1) {
|
|
23
|
-
report('At most one access-control tag may be present on a jsdoc block.');
|
|
24
|
-
}
|
|
25
|
-
}, {
|
|
26
|
-
checkPrivate: true,
|
|
27
|
-
iterateAllJsdocs: true,
|
|
28
|
-
meta: {
|
|
29
|
-
docs: {
|
|
30
|
-
description: 'Checks that `@access` tags have a valid value.',
|
|
31
|
-
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-access.md#repos-sticky-header',
|
|
32
|
-
},
|
|
33
|
-
type: 'suggestion',
|
|
34
|
-
},
|
|
35
|
-
});
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
-
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
-
};
|
|
5
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
-
const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
|
|
7
|
-
exports.default = (0, iterateJsdoc_js_1.default)(({ context, indent, jsdocNode, report, sourceCode, }) => {
|
|
8
|
-
const { innerIndent = 1, } = context.options[0] || {};
|
|
9
|
-
// `indent` is whitespace from line 1 (`/**`), so slice and account for "/".
|
|
10
|
-
const indentLevel = indent.length + innerIndent;
|
|
11
|
-
const sourceLines = sourceCode.getText(jsdocNode).split('\n')
|
|
12
|
-
.slice(1)
|
|
13
|
-
.map((line, number) => {
|
|
14
|
-
return {
|
|
15
|
-
line: line.split('*')[0],
|
|
16
|
-
number,
|
|
17
|
-
};
|
|
18
|
-
})
|
|
19
|
-
.filter(({ line, }) => {
|
|
20
|
-
return !line.trimStart().length;
|
|
21
|
-
});
|
|
22
|
-
/** @type {import('eslint').Rule.ReportFixer} */
|
|
23
|
-
const fix = (fixer) => {
|
|
24
|
-
const replacement = sourceCode.getText(jsdocNode).split('\n')
|
|
25
|
-
.map((line, index) => {
|
|
26
|
-
// Ignore the first line and all lines not starting with `*`
|
|
27
|
-
const ignored = !index || line.split('*')[0].trimStart().length;
|
|
28
|
-
return ignored ? line : `${indent}${''.padStart(innerIndent, ' ')}${line.trimStart()}`;
|
|
29
|
-
})
|
|
30
|
-
.join('\n');
|
|
31
|
-
return fixer.replaceText(jsdocNode, replacement);
|
|
32
|
-
};
|
|
33
|
-
sourceLines.some(({ line, number, }) => {
|
|
34
|
-
if (line.length !== indentLevel) {
|
|
35
|
-
report('Expected JSDoc block to be aligned.', fix, {
|
|
36
|
-
line: number + 1,
|
|
37
|
-
});
|
|
38
|
-
return true;
|
|
39
|
-
}
|
|
40
|
-
return false;
|
|
41
|
-
});
|
|
42
|
-
}, {
|
|
43
|
-
iterateAllJsdocs: true,
|
|
44
|
-
meta: {
|
|
45
|
-
docs: {
|
|
46
|
-
description: 'Reports invalid alignment of JSDoc block asterisks.',
|
|
47
|
-
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-alignment.md#repos-sticky-header',
|
|
48
|
-
},
|
|
49
|
-
fixable: 'code',
|
|
50
|
-
schema: [
|
|
51
|
-
{
|
|
52
|
-
additionalProperties: false,
|
|
53
|
-
properties: {
|
|
54
|
-
innerIndent: {
|
|
55
|
-
default: 1,
|
|
56
|
-
type: 'integer',
|
|
57
|
-
},
|
|
58
|
-
},
|
|
59
|
-
},
|
|
60
|
-
],
|
|
61
|
-
type: 'layout',
|
|
62
|
-
},
|
|
63
|
-
});
|
|
@@ -1,486 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
-
if (k2 === undefined) k2 = k;
|
|
4
|
-
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
-
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
-
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
-
}
|
|
8
|
-
Object.defineProperty(o, k2, desc);
|
|
9
|
-
}) : (function(o, m, k, k2) {
|
|
10
|
-
if (k2 === undefined) k2 = k;
|
|
11
|
-
o[k2] = m[k];
|
|
12
|
-
}));
|
|
13
|
-
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
-
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
-
}) : function(o, v) {
|
|
16
|
-
o["default"] = v;
|
|
17
|
-
});
|
|
18
|
-
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
-
var ownKeys = function(o) {
|
|
20
|
-
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
-
var ar = [];
|
|
22
|
-
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
-
return ar;
|
|
24
|
-
};
|
|
25
|
-
return ownKeys(o);
|
|
26
|
-
};
|
|
27
|
-
return function (mod) {
|
|
28
|
-
if (mod && mod.__esModule) return mod;
|
|
29
|
-
var result = {};
|
|
30
|
-
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
-
__setModuleDefault(result, mod);
|
|
32
|
-
return result;
|
|
33
|
-
};
|
|
34
|
-
})();
|
|
35
|
-
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
36
|
-
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
37
|
-
};
|
|
38
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
39
|
-
const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
|
|
40
|
-
const eslint_1 = __importStar(require("eslint"));
|
|
41
|
-
const semver_1 = __importDefault(require("semver"));
|
|
42
|
-
const {
|
|
43
|
-
// @ts-expect-error Older ESLint
|
|
44
|
-
CLIEngine, } = eslint_1.default;
|
|
45
|
-
const zeroBasedLineIndexAdjust = -1;
|
|
46
|
-
const likelyNestedJSDocIndentSpace = 1;
|
|
47
|
-
const preTagSpaceLength = 1;
|
|
48
|
-
// If a space is present, we should ignore it
|
|
49
|
-
const firstLinePrefixLength = preTagSpaceLength;
|
|
50
|
-
const hasCaptionRegex = /^\s*<caption>([\s\S]*?)<\/caption>/v;
|
|
51
|
-
/**
|
|
52
|
-
* @param {string} str
|
|
53
|
-
* @returns {string}
|
|
54
|
-
*/
|
|
55
|
-
const escapeStringRegexp = (str) => {
|
|
56
|
-
return str.replaceAll(/[.*+?^$\{\}\(\)\|\[\]\\]/gv, '\\$&');
|
|
57
|
-
};
|
|
58
|
-
/**
|
|
59
|
-
* @param {string} str
|
|
60
|
-
* @param {string} ch
|
|
61
|
-
* @returns {import('../iterateJsdoc.js').Integer}
|
|
62
|
-
*/
|
|
63
|
-
const countChars = (str, ch) => {
|
|
64
|
-
return (str.match(new RegExp(escapeStringRegexp(ch), 'gv')) || []).length;
|
|
65
|
-
};
|
|
66
|
-
/** @type {import('eslint').Linter.RulesRecord} */
|
|
67
|
-
const defaultMdRules = {
|
|
68
|
-
// "always" newline rule at end unlikely in sample code
|
|
69
|
-
'eol-last': 0,
|
|
70
|
-
// Wouldn't generally expect example paths to resolve relative to JS file
|
|
71
|
-
'import/no-unresolved': 0,
|
|
72
|
-
// Snippets likely too short to always include import/export info
|
|
73
|
-
'import/unambiguous': 0,
|
|
74
|
-
'jsdoc/require-file-overview': 0,
|
|
75
|
-
// The end of a multiline comment would end the comment the example is in.
|
|
76
|
-
'jsdoc/require-jsdoc': 0,
|
|
77
|
-
// Unlikely to have inadvertent debugging within examples
|
|
78
|
-
'no-console': 0,
|
|
79
|
-
// Often wish to start `@example` code after newline; also may use
|
|
80
|
-
// empty lines for spacing
|
|
81
|
-
'no-multiple-empty-lines': 0,
|
|
82
|
-
// Many variables in examples will be `undefined`
|
|
83
|
-
'no-undef': 0,
|
|
84
|
-
// Common to define variables for clarity without always using them
|
|
85
|
-
'no-unused-vars': 0,
|
|
86
|
-
// See import/no-unresolved
|
|
87
|
-
'node/no-missing-import': 0,
|
|
88
|
-
'node/no-missing-require': 0,
|
|
89
|
-
// Can generally look nicer to pad a little even if code imposes more stringency
|
|
90
|
-
'padded-blocks': 0,
|
|
91
|
-
};
|
|
92
|
-
/** @type {import('eslint').Linter.RulesRecord} */
|
|
93
|
-
const defaultExpressionRules = {
|
|
94
|
-
...defaultMdRules,
|
|
95
|
-
'chai-friendly/no-unused-expressions': 'off',
|
|
96
|
-
'no-empty-function': 'off',
|
|
97
|
-
'no-new': 'off',
|
|
98
|
-
'no-unused-expressions': 'off',
|
|
99
|
-
quotes: [
|
|
100
|
-
'error', 'double',
|
|
101
|
-
],
|
|
102
|
-
semi: [
|
|
103
|
-
'error', 'never',
|
|
104
|
-
],
|
|
105
|
-
strict: 'off',
|
|
106
|
-
};
|
|
107
|
-
/**
|
|
108
|
-
* @param {string} text
|
|
109
|
-
* @returns {[
|
|
110
|
-
* import('../iterateJsdoc.js').Integer,
|
|
111
|
-
* import('../iterateJsdoc.js').Integer
|
|
112
|
-
* ]}
|
|
113
|
-
*/
|
|
114
|
-
const getLinesCols = (text) => {
|
|
115
|
-
const matchLines = countChars(text, '\n');
|
|
116
|
-
const colDelta = matchLines ?
|
|
117
|
-
text.slice(text.lastIndexOf('\n') + 1).length :
|
|
118
|
-
text.length;
|
|
119
|
-
return [
|
|
120
|
-
matchLines, colDelta,
|
|
121
|
-
];
|
|
122
|
-
};
|
|
123
|
-
exports.default = (0, iterateJsdoc_js_1.default)(({ context, globalState, report, utils, }) => {
|
|
124
|
-
if (semver_1.default.gte(eslint_1.ESLint.version, '8.0.0')) {
|
|
125
|
-
report('This rule does not work for ESLint 8+; you should disable this rule and use' +
|
|
126
|
-
'the processor mentioned in the docs.', null, {
|
|
127
|
-
column: 1,
|
|
128
|
-
line: 1,
|
|
129
|
-
});
|
|
130
|
-
return;
|
|
131
|
-
}
|
|
132
|
-
if (!globalState.has('checkExamples-matchingFileName')) {
|
|
133
|
-
globalState.set('checkExamples-matchingFileName', new Map());
|
|
134
|
-
}
|
|
135
|
-
const matchingFileNameMap = /** @type {Map<string, string>} */ (globalState.get('checkExamples-matchingFileName'));
|
|
136
|
-
const options = context.options[0] || {};
|
|
137
|
-
let { exampleCodeRegex = null, rejectExampleCodeRegex = null, } = options;
|
|
138
|
-
const { allowInlineConfig = true, baseConfig = {}, captionRequired = false, checkDefaults = false, checkEslintrc = true, checkParams = false, checkProperties = false, configFile, matchingFileName = null, matchingFileNameDefaults = null, matchingFileNameParams = null, matchingFileNameProperties = null, noDefaultExampleRules = false, paddedIndent = 0, reportUnusedDisableDirectives = true, } = options;
|
|
139
|
-
// Make this configurable?
|
|
140
|
-
/**
|
|
141
|
-
* @type {never[]}
|
|
142
|
-
*/
|
|
143
|
-
const rulePaths = [];
|
|
144
|
-
const mdRules = noDefaultExampleRules ? undefined : defaultMdRules;
|
|
145
|
-
const expressionRules = noDefaultExampleRules ? undefined : defaultExpressionRules;
|
|
146
|
-
if (exampleCodeRegex) {
|
|
147
|
-
exampleCodeRegex = utils.getRegexFromString(exampleCodeRegex);
|
|
148
|
-
}
|
|
149
|
-
if (rejectExampleCodeRegex) {
|
|
150
|
-
rejectExampleCodeRegex = utils.getRegexFromString(rejectExampleCodeRegex);
|
|
151
|
-
}
|
|
152
|
-
/**
|
|
153
|
-
* @param {{
|
|
154
|
-
* filename: string,
|
|
155
|
-
* defaultFileName: string|undefined,
|
|
156
|
-
* source: string,
|
|
157
|
-
* targetTagName: string,
|
|
158
|
-
* rules?: import('eslint').Linter.RulesRecord|undefined,
|
|
159
|
-
* lines?: import('../iterateJsdoc.js').Integer,
|
|
160
|
-
* cols?: import('../iterateJsdoc.js').Integer,
|
|
161
|
-
* skipInit?: boolean,
|
|
162
|
-
* sources?: {
|
|
163
|
-
* nonJSPrefacingCols: import('../iterateJsdoc.js').Integer,
|
|
164
|
-
* nonJSPrefacingLines: import('../iterateJsdoc.js').Integer,
|
|
165
|
-
* string: string,
|
|
166
|
-
* }[],
|
|
167
|
-
* tag?: import('comment-parser').Spec & {
|
|
168
|
-
* line?: import('../iterateJsdoc.js').Integer,
|
|
169
|
-
* }|{
|
|
170
|
-
* line: import('../iterateJsdoc.js').Integer,
|
|
171
|
-
* }
|
|
172
|
-
* }} cfg
|
|
173
|
-
*/
|
|
174
|
-
const checkSource = ({ cols = 0, defaultFileName, filename, lines = 0, rules = expressionRules, skipInit, source, sources = [], tag = {
|
|
175
|
-
line: 0,
|
|
176
|
-
}, targetTagName, }) => {
|
|
177
|
-
if (!skipInit) {
|
|
178
|
-
sources.push({
|
|
179
|
-
nonJSPrefacingCols: cols,
|
|
180
|
-
nonJSPrefacingLines: lines,
|
|
181
|
-
string: source,
|
|
182
|
-
});
|
|
183
|
-
}
|
|
184
|
-
/**
|
|
185
|
-
* @param {{
|
|
186
|
-
* nonJSPrefacingCols: import('../iterateJsdoc.js').Integer,
|
|
187
|
-
* nonJSPrefacingLines: import('../iterateJsdoc.js').Integer,
|
|
188
|
-
* string: string
|
|
189
|
-
* }} cfg
|
|
190
|
-
*/
|
|
191
|
-
const checkRules = function ({ nonJSPrefacingCols, nonJSPrefacingLines, string, }) {
|
|
192
|
-
const cliConfig = {
|
|
193
|
-
allowInlineConfig,
|
|
194
|
-
baseConfig,
|
|
195
|
-
configFile,
|
|
196
|
-
reportUnusedDisableDirectives,
|
|
197
|
-
rulePaths,
|
|
198
|
-
rules,
|
|
199
|
-
useEslintrc: checkEslintrc,
|
|
200
|
-
};
|
|
201
|
-
const cliConfigStr = JSON.stringify(cliConfig);
|
|
202
|
-
const src = paddedIndent ?
|
|
203
|
-
string.replaceAll(new RegExp(`(^|\n) {${paddedIndent}}(?!$)`, 'gv'), '\n') :
|
|
204
|
-
string;
|
|
205
|
-
// Programmatic ESLint API: https://eslint.org/docs/developer-guide/nodejs-api
|
|
206
|
-
const fileNameMapKey = filename ?
|
|
207
|
-
'a' + cliConfigStr + filename :
|
|
208
|
-
'b' + cliConfigStr + defaultFileName;
|
|
209
|
-
const file = filename || defaultFileName;
|
|
210
|
-
let cliFile;
|
|
211
|
-
if (matchingFileNameMap.has(fileNameMapKey)) {
|
|
212
|
-
cliFile = matchingFileNameMap.get(fileNameMapKey);
|
|
213
|
-
}
|
|
214
|
-
else {
|
|
215
|
-
const cli = new CLIEngine(cliConfig);
|
|
216
|
-
let config;
|
|
217
|
-
if (filename || checkEslintrc) {
|
|
218
|
-
config = cli.getConfigForFile(file);
|
|
219
|
-
}
|
|
220
|
-
// We need a new instance to ensure that the rules that may only
|
|
221
|
-
// be available to `file` (if it has its own `.eslintrc`),
|
|
222
|
-
// will be defined.
|
|
223
|
-
cliFile = new CLIEngine({
|
|
224
|
-
allowInlineConfig,
|
|
225
|
-
baseConfig: {
|
|
226
|
-
...baseConfig,
|
|
227
|
-
...config,
|
|
228
|
-
},
|
|
229
|
-
configFile,
|
|
230
|
-
reportUnusedDisableDirectives,
|
|
231
|
-
rulePaths,
|
|
232
|
-
rules,
|
|
233
|
-
useEslintrc: false,
|
|
234
|
-
});
|
|
235
|
-
matchingFileNameMap.set(fileNameMapKey, cliFile);
|
|
236
|
-
}
|
|
237
|
-
const { results: [{ messages, },], } = cliFile.executeOnText(src);
|
|
238
|
-
if (!('line' in tag)) {
|
|
239
|
-
tag.line = tag.source[0].number;
|
|
240
|
-
}
|
|
241
|
-
// NOTE: `tag.line` can be 0 if of form `/** @tag ... */`
|
|
242
|
-
const codeStartLine = /**
|
|
243
|
-
* @type {import('comment-parser').Spec & {
|
|
244
|
-
* line: import('../iterateJsdoc.js').Integer,
|
|
245
|
-
* }}
|
|
246
|
-
*/ (tag).line + nonJSPrefacingLines;
|
|
247
|
-
const codeStartCol = likelyNestedJSDocIndentSpace;
|
|
248
|
-
for (const { column, line, message, ruleId, severity, } of messages) {
|
|
249
|
-
const startLine = codeStartLine + line + zeroBasedLineIndexAdjust;
|
|
250
|
-
const startCol = codeStartCol + (
|
|
251
|
-
// This might not work for line 0, but line 0 is unlikely for examples
|
|
252
|
-
line <= 1 ? nonJSPrefacingCols + firstLinePrefixLength : preTagSpaceLength) + column;
|
|
253
|
-
report('@' + targetTagName + ' ' + (severity === 2 ? 'error' : 'warning') +
|
|
254
|
-
(ruleId ? ' (' + ruleId + ')' : '') + ': ' +
|
|
255
|
-
message, null, {
|
|
256
|
-
column: startCol,
|
|
257
|
-
line: startLine,
|
|
258
|
-
});
|
|
259
|
-
}
|
|
260
|
-
};
|
|
261
|
-
for (const targetSource of sources) {
|
|
262
|
-
checkRules(targetSource);
|
|
263
|
-
}
|
|
264
|
-
};
|
|
265
|
-
/**
|
|
266
|
-
*
|
|
267
|
-
* @param {string} filename
|
|
268
|
-
* @param {string} [ext] Since `eslint-plugin-markdown` v2, and
|
|
269
|
-
* ESLint 7, this is the default which other JS-fenced rules will used.
|
|
270
|
-
* Formerly "md" was the default.
|
|
271
|
-
* @returns {{defaultFileName: string|undefined, filename: string}}
|
|
272
|
-
*/
|
|
273
|
-
const getFilenameInfo = (filename, ext = 'md/*.js') => {
|
|
274
|
-
let defaultFileName;
|
|
275
|
-
if (!filename) {
|
|
276
|
-
const jsFileName = context.getFilename();
|
|
277
|
-
if (typeof jsFileName === 'string' && jsFileName.includes('.')) {
|
|
278
|
-
defaultFileName = jsFileName.replace(/\.[^.]*$/v, `.${ext}`);
|
|
279
|
-
}
|
|
280
|
-
else {
|
|
281
|
-
defaultFileName = `dummy.${ext}`;
|
|
282
|
-
}
|
|
283
|
-
}
|
|
284
|
-
return {
|
|
285
|
-
defaultFileName,
|
|
286
|
-
filename,
|
|
287
|
-
};
|
|
288
|
-
};
|
|
289
|
-
if (checkDefaults) {
|
|
290
|
-
const filenameInfo = getFilenameInfo(matchingFileNameDefaults, 'jsdoc-defaults');
|
|
291
|
-
utils.forEachPreferredTag('default', (tag, targetTagName) => {
|
|
292
|
-
if (!tag.description.trim()) {
|
|
293
|
-
return;
|
|
294
|
-
}
|
|
295
|
-
checkSource({
|
|
296
|
-
source: `(${utils.getTagDescription(tag)})`,
|
|
297
|
-
targetTagName,
|
|
298
|
-
...filenameInfo,
|
|
299
|
-
});
|
|
300
|
-
});
|
|
301
|
-
}
|
|
302
|
-
if (checkParams) {
|
|
303
|
-
const filenameInfo = getFilenameInfo(matchingFileNameParams, 'jsdoc-params');
|
|
304
|
-
utils.forEachPreferredTag('param', (tag, targetTagName) => {
|
|
305
|
-
if (!tag.default || !tag.default.trim()) {
|
|
306
|
-
return;
|
|
307
|
-
}
|
|
308
|
-
checkSource({
|
|
309
|
-
source: `(${tag.default})`,
|
|
310
|
-
targetTagName,
|
|
311
|
-
...filenameInfo,
|
|
312
|
-
});
|
|
313
|
-
});
|
|
314
|
-
}
|
|
315
|
-
if (checkProperties) {
|
|
316
|
-
const filenameInfo = getFilenameInfo(matchingFileNameProperties, 'jsdoc-properties');
|
|
317
|
-
utils.forEachPreferredTag('property', (tag, targetTagName) => {
|
|
318
|
-
if (!tag.default || !tag.default.trim()) {
|
|
319
|
-
return;
|
|
320
|
-
}
|
|
321
|
-
checkSource({
|
|
322
|
-
source: `(${tag.default})`,
|
|
323
|
-
targetTagName,
|
|
324
|
-
...filenameInfo,
|
|
325
|
-
});
|
|
326
|
-
});
|
|
327
|
-
}
|
|
328
|
-
const tagName = /** @type {string} */ (utils.getPreferredTagName({
|
|
329
|
-
tagName: 'example',
|
|
330
|
-
}));
|
|
331
|
-
if (!utils.hasTag(tagName)) {
|
|
332
|
-
return;
|
|
333
|
-
}
|
|
334
|
-
const matchingFilenameInfo = getFilenameInfo(matchingFileName);
|
|
335
|
-
utils.forEachPreferredTag('example', (tag, targetTagName) => {
|
|
336
|
-
let source = /** @type {string} */ (utils.getTagDescription(tag));
|
|
337
|
-
const match = source.match(hasCaptionRegex);
|
|
338
|
-
if (captionRequired && (!match || !match[1].trim())) {
|
|
339
|
-
report('Caption is expected for examples.', null, tag);
|
|
340
|
-
}
|
|
341
|
-
source = source.replace(hasCaptionRegex, '');
|
|
342
|
-
const [lines, cols,] = match ? getLinesCols(match[0]) : [
|
|
343
|
-
0, 0,
|
|
344
|
-
];
|
|
345
|
-
if (exampleCodeRegex && !exampleCodeRegex.test(source) ||
|
|
346
|
-
rejectExampleCodeRegex && rejectExampleCodeRegex.test(source)) {
|
|
347
|
-
return;
|
|
348
|
-
}
|
|
349
|
-
const sources = [];
|
|
350
|
-
let skipInit = false;
|
|
351
|
-
if (exampleCodeRegex) {
|
|
352
|
-
let nonJSPrefacingCols = 0;
|
|
353
|
-
let nonJSPrefacingLines = 0;
|
|
354
|
-
let startingIndex = 0;
|
|
355
|
-
let lastStringCount = 0;
|
|
356
|
-
let exampleCode;
|
|
357
|
-
exampleCodeRegex.lastIndex = 0;
|
|
358
|
-
while ((exampleCode = exampleCodeRegex.exec(source)) !== null) {
|
|
359
|
-
const { '0': n0, '1': n1, index, } = exampleCode;
|
|
360
|
-
// Count anything preceding user regex match (can affect line numbering)
|
|
361
|
-
const preMatch = source.slice(startingIndex, index);
|
|
362
|
-
const [preMatchLines, colDelta,] = getLinesCols(preMatch);
|
|
363
|
-
let nonJSPreface;
|
|
364
|
-
let nonJSPrefaceLineCount;
|
|
365
|
-
if (n1) {
|
|
366
|
-
const idx = n0.indexOf(n1);
|
|
367
|
-
nonJSPreface = n0.slice(0, idx);
|
|
368
|
-
nonJSPrefaceLineCount = countChars(nonJSPreface, '\n');
|
|
369
|
-
}
|
|
370
|
-
else {
|
|
371
|
-
nonJSPreface = '';
|
|
372
|
-
nonJSPrefaceLineCount = 0;
|
|
373
|
-
}
|
|
374
|
-
nonJSPrefacingLines += lastStringCount + preMatchLines + nonJSPrefaceLineCount;
|
|
375
|
-
// Ignore `preMatch` delta if newlines here
|
|
376
|
-
if (nonJSPrefaceLineCount) {
|
|
377
|
-
const charsInLastLine = nonJSPreface.slice(nonJSPreface.lastIndexOf('\n') + 1).length;
|
|
378
|
-
nonJSPrefacingCols += charsInLastLine;
|
|
379
|
-
}
|
|
380
|
-
else {
|
|
381
|
-
nonJSPrefacingCols += colDelta + nonJSPreface.length;
|
|
382
|
-
}
|
|
383
|
-
const string = n1 || n0;
|
|
384
|
-
sources.push({
|
|
385
|
-
nonJSPrefacingCols,
|
|
386
|
-
nonJSPrefacingLines,
|
|
387
|
-
string,
|
|
388
|
-
});
|
|
389
|
-
startingIndex = exampleCodeRegex.lastIndex;
|
|
390
|
-
lastStringCount = countChars(string, '\n');
|
|
391
|
-
if (!exampleCodeRegex.global) {
|
|
392
|
-
break;
|
|
393
|
-
}
|
|
394
|
-
}
|
|
395
|
-
skipInit = true;
|
|
396
|
-
}
|
|
397
|
-
checkSource({
|
|
398
|
-
cols,
|
|
399
|
-
lines,
|
|
400
|
-
rules: mdRules,
|
|
401
|
-
skipInit,
|
|
402
|
-
source,
|
|
403
|
-
sources,
|
|
404
|
-
tag,
|
|
405
|
-
targetTagName,
|
|
406
|
-
...matchingFilenameInfo,
|
|
407
|
-
});
|
|
408
|
-
});
|
|
409
|
-
}, {
|
|
410
|
-
iterateAllJsdocs: true,
|
|
411
|
-
meta: {
|
|
412
|
-
docs: {
|
|
413
|
-
description: 'Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.',
|
|
414
|
-
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-examples.md#repos-sticky-header',
|
|
415
|
-
},
|
|
416
|
-
schema: [
|
|
417
|
-
{
|
|
418
|
-
additionalProperties: false,
|
|
419
|
-
properties: {
|
|
420
|
-
allowInlineConfig: {
|
|
421
|
-
default: true,
|
|
422
|
-
type: 'boolean',
|
|
423
|
-
},
|
|
424
|
-
baseConfig: {
|
|
425
|
-
type: 'object',
|
|
426
|
-
},
|
|
427
|
-
captionRequired: {
|
|
428
|
-
default: false,
|
|
429
|
-
type: 'boolean',
|
|
430
|
-
},
|
|
431
|
-
checkDefaults: {
|
|
432
|
-
default: false,
|
|
433
|
-
type: 'boolean',
|
|
434
|
-
},
|
|
435
|
-
checkEslintrc: {
|
|
436
|
-
default: true,
|
|
437
|
-
type: 'boolean',
|
|
438
|
-
},
|
|
439
|
-
checkParams: {
|
|
440
|
-
default: false,
|
|
441
|
-
type: 'boolean',
|
|
442
|
-
},
|
|
443
|
-
checkProperties: {
|
|
444
|
-
default: false,
|
|
445
|
-
type: 'boolean',
|
|
446
|
-
},
|
|
447
|
-
configFile: {
|
|
448
|
-
type: 'string',
|
|
449
|
-
},
|
|
450
|
-
exampleCodeRegex: {
|
|
451
|
-
type: 'string',
|
|
452
|
-
},
|
|
453
|
-
matchingFileName: {
|
|
454
|
-
type: 'string',
|
|
455
|
-
},
|
|
456
|
-
matchingFileNameDefaults: {
|
|
457
|
-
type: 'string',
|
|
458
|
-
},
|
|
459
|
-
matchingFileNameParams: {
|
|
460
|
-
type: 'string',
|
|
461
|
-
},
|
|
462
|
-
matchingFileNameProperties: {
|
|
463
|
-
type: 'string',
|
|
464
|
-
},
|
|
465
|
-
noDefaultExampleRules: {
|
|
466
|
-
default: false,
|
|
467
|
-
type: 'boolean',
|
|
468
|
-
},
|
|
469
|
-
paddedIndent: {
|
|
470
|
-
default: 0,
|
|
471
|
-
type: 'integer',
|
|
472
|
-
},
|
|
473
|
-
rejectExampleCodeRegex: {
|
|
474
|
-
type: 'string',
|
|
475
|
-
},
|
|
476
|
-
reportUnusedDisableDirectives: {
|
|
477
|
-
default: true,
|
|
478
|
-
type: 'boolean',
|
|
479
|
-
},
|
|
480
|
-
},
|
|
481
|
-
type: 'object',
|
|
482
|
-
},
|
|
483
|
-
],
|
|
484
|
-
type: 'suggestion',
|
|
485
|
-
},
|
|
486
|
-
});
|
|
@@ -1,66 +0,0 @@
|
|
|
1
|
-
"use strict";
|
|
2
|
-
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
-
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
-
};
|
|
5
|
-
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
-
const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
|
|
7
|
-
/**
|
|
8
|
-
* @param {string} str
|
|
9
|
-
* @param {string[]} excludeTags
|
|
10
|
-
* @returns {string}
|
|
11
|
-
*/
|
|
12
|
-
const maskExcludedContent = (str, excludeTags) => {
|
|
13
|
-
const regContent = new RegExp(`([ \\t]+\\*)[ \\t]@(?:${excludeTags.join('|')})(?=[ \\n])([\\w\\|\\W]*?\\n)(?=[ \\t]*\\*(?:[ \\t]*@\\w+\\s|\\/))`, 'gv');
|
|
14
|
-
return str.replace(regContent, (_match, margin, code) => {
|
|
15
|
-
return (margin + '\n').repeat(code.match(/\n/gv).length);
|
|
16
|
-
});
|
|
17
|
-
};
|
|
18
|
-
/**
|
|
19
|
-
* @param {string} str
|
|
20
|
-
* @returns {string}
|
|
21
|
-
*/
|
|
22
|
-
const maskCodeBlocks = (str) => {
|
|
23
|
-
const regContent = /([ \t]+\*)[ \t]```[^\n]*?([\w\|\W]*?\n)(?=[ \t]*\*(?:[ \t]*(?:```|@\w+\s)|\/))/gv;
|
|
24
|
-
return str.replaceAll(regContent, (_match, margin, code) => {
|
|
25
|
-
return (margin + '\n').repeat(code.match(/\n/gv).length);
|
|
26
|
-
});
|
|
27
|
-
};
|
|
28
|
-
exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdocNode, report, sourceCode, }) => {
|
|
29
|
-
const options = context.options[0] || {};
|
|
30
|
-
const /** @type {{excludeTags: string[]}} */ { excludeTags = [
|
|
31
|
-
'example',
|
|
32
|
-
], } = options;
|
|
33
|
-
const reg = /^(?:\/?\**|[ \t]*)\*[ \t]{2}/gmv;
|
|
34
|
-
const textWithoutCodeBlocks = maskCodeBlocks(sourceCode.getText(jsdocNode));
|
|
35
|
-
const text = excludeTags.length ? maskExcludedContent(textWithoutCodeBlocks, excludeTags) : textWithoutCodeBlocks;
|
|
36
|
-
if (reg.test(text)) {
|
|
37
|
-
const lineBreaks = text.slice(0, reg.lastIndex).match(/\n/gv) || [];
|
|
38
|
-
report('There must be no indentation.', null, {
|
|
39
|
-
line: lineBreaks.length,
|
|
40
|
-
});
|
|
41
|
-
}
|
|
42
|
-
}, {
|
|
43
|
-
iterateAllJsdocs: true,
|
|
44
|
-
meta: {
|
|
45
|
-
docs: {
|
|
46
|
-
description: 'Reports invalid padding inside JSDoc blocks.',
|
|
47
|
-
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-indentation.md#repos-sticky-header',
|
|
48
|
-
},
|
|
49
|
-
schema: [
|
|
50
|
-
{
|
|
51
|
-
additionalProperties: false,
|
|
52
|
-
properties: {
|
|
53
|
-
excludeTags: {
|
|
54
|
-
items: {
|
|
55
|
-
pattern: '^\\S+$',
|
|
56
|
-
type: 'string',
|
|
57
|
-
},
|
|
58
|
-
type: 'array',
|
|
59
|
-
},
|
|
60
|
-
},
|
|
61
|
-
type: 'object',
|
|
62
|
-
},
|
|
63
|
-
],
|
|
64
|
-
type: 'layout',
|
|
65
|
-
},
|
|
66
|
-
});
|