464 lines
No EOL
13 KiB
JavaScript
Executable file
464 lines
No EOL
13 KiB
JavaScript
Executable file
"use strict";
|
|
|
|
Object.defineProperty(exports, "__esModule", {
|
|
value: true
|
|
});
|
|
exports.default = void 0;
|
|
|
|
var _eslint = require("eslint");
|
|
|
|
var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc"));
|
|
|
|
function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
|
|
|
|
// Todo: When peerDeps bump to ESLint 7, see about replacing `CLIEngine`
|
|
// with non-deprecated `ESLint` class:
|
|
// https://github.com/eslint/eslint/blob/master/docs/user-guide/migrating-to-7.0.0.md#-the-cliengine-class-has-been-deprecated
|
|
const zeroBasedLineIndexAdjust = -1;
|
|
const likelyNestedJSDocIndentSpace = 1;
|
|
const preTagSpaceLength = 1; // If a space is present, we should ignore it
|
|
|
|
const firstLinePrefixLength = preTagSpaceLength;
|
|
const hasCaptionRegex = /^\s*<caption>(.*?)<\/caption>/u;
|
|
|
|
const escapeStringRegexp = str => {
|
|
return str.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
|
|
};
|
|
|
|
const countChars = (str, ch) => {
|
|
return (str.match(new RegExp(escapeStringRegexp(ch), 'gu')) || []).length;
|
|
};
|
|
|
|
const getRegexFromString = regexString => {
|
|
const match = regexString.match(/^\/(.*)\/([gimyus]*)$/u);
|
|
let flags = 'u';
|
|
let regex = regexString;
|
|
|
|
if (match) {
|
|
[, regex, flags] = match;
|
|
|
|
if (!flags) {
|
|
flags = 'u';
|
|
}
|
|
|
|
const uniqueFlags = [...new Set(flags)];
|
|
flags = uniqueFlags.join('');
|
|
}
|
|
|
|
return new RegExp(regex, flags);
|
|
};
|
|
|
|
const defaultMdRules = {
|
|
// "always" newline rule at end unlikely in sample code
|
|
'eol-last': 0,
|
|
// Wouldn't generally expect example paths to resolve relative to JS file
|
|
'import/no-unresolved': 0,
|
|
// Snippets likely too short to always include import/export info
|
|
'import/unambiguous': 0,
|
|
'jsdoc/require-file-overview': 0,
|
|
// The end of a multiline comment would end the comment the example is in.
|
|
'jsdoc/require-jsdoc': 0,
|
|
// Unlikely to have inadvertent debugging within examples
|
|
'no-console': 0,
|
|
// Often wish to start `@example` code after newline; also may use
|
|
// empty lines for spacing
|
|
'no-multiple-empty-lines': 0,
|
|
// Many variables in examples will be `undefined`
|
|
'no-undef': 0,
|
|
// Common to define variables for clarity without always using them
|
|
'no-unused-vars': 0,
|
|
// See import/no-unresolved
|
|
'node/no-missing-import': 0,
|
|
'node/no-missing-require': 0,
|
|
// Can generally look nicer to pad a little even if code imposes more stringency
|
|
'padded-blocks': 0
|
|
};
|
|
const defaultExpressionRules = { ...defaultMdRules,
|
|
'no-unused-expressions': 'off',
|
|
quotes: ['error', 'double'],
|
|
semi: ['error', 'never'],
|
|
strict: 'off'
|
|
};
|
|
|
|
var _default = (0, _iterateJsdoc.default)(({
|
|
report,
|
|
utils,
|
|
context,
|
|
globalState
|
|
}) => {
|
|
if (!globalState.has('checkExamples-matchingFileName')) {
|
|
globalState.set('checkExamples-matchingFileName', new Map());
|
|
}
|
|
|
|
const matchingFileNameMap = globalState.get('checkExamples-matchingFileName');
|
|
const options = context.options[0] || {};
|
|
let {
|
|
exampleCodeRegex = null,
|
|
rejectExampleCodeRegex = null
|
|
} = options;
|
|
const {
|
|
checkDefaults = false,
|
|
checkParams = false,
|
|
checkProperties = false,
|
|
noDefaultExampleRules = false,
|
|
checkEslintrc = true,
|
|
matchingFileName = null,
|
|
matchingFileNameDefaults = null,
|
|
matchingFileNameParams = null,
|
|
matchingFileNameProperties = null,
|
|
paddedIndent = 0,
|
|
baseConfig = {},
|
|
configFile,
|
|
allowInlineConfig = true,
|
|
reportUnusedDisableDirectives = true,
|
|
captionRequired = false
|
|
} = options; // Make this configurable?
|
|
|
|
const rulePaths = [];
|
|
const mdRules = noDefaultExampleRules ? undefined : defaultMdRules;
|
|
const expressionRules = noDefaultExampleRules ? undefined : defaultExpressionRules;
|
|
|
|
if (exampleCodeRegex) {
|
|
exampleCodeRegex = getRegexFromString(exampleCodeRegex);
|
|
}
|
|
|
|
if (rejectExampleCodeRegex) {
|
|
rejectExampleCodeRegex = getRegexFromString(rejectExampleCodeRegex);
|
|
}
|
|
|
|
const checkSource = ({
|
|
filename,
|
|
defaultFileName,
|
|
rules = expressionRules,
|
|
skipInit,
|
|
source,
|
|
targetTagName,
|
|
sources = [],
|
|
tag = {
|
|
line: 0
|
|
}
|
|
}) => {
|
|
if (!skipInit) {
|
|
sources.push({
|
|
nonJSPrefacingCols: 0,
|
|
nonJSPrefacingLines: 0,
|
|
string: source
|
|
});
|
|
} // Todo: Make fixable
|
|
// Todo: Fix whitespace indent
|
|
|
|
|
|
const checkRules = function ({
|
|
nonJSPrefacingCols,
|
|
nonJSPrefacingLines,
|
|
string
|
|
}) {
|
|
const cliConfig = {
|
|
allowInlineConfig,
|
|
baseConfig,
|
|
configFile,
|
|
reportUnusedDisableDirectives,
|
|
rulePaths,
|
|
rules,
|
|
useEslintrc: checkEslintrc
|
|
};
|
|
const cliConfigStr = JSON.stringify(cliConfig);
|
|
const src = paddedIndent ? string.replace(new RegExp(`(^|\n) {${paddedIndent}}(?!$)`, 'gu'), '\n') : string; // Programmatic ESLint API: https://eslint.org/docs/developer-guide/nodejs-api
|
|
|
|
const fileNameMapKey = filename ? 'a' + cliConfigStr + filename : 'b' + cliConfigStr + defaultFileName;
|
|
const file = filename || defaultFileName;
|
|
let cliFile;
|
|
|
|
if (matchingFileNameMap.has(fileNameMapKey)) {
|
|
cliFile = matchingFileNameMap.get(fileNameMapKey);
|
|
} else {
|
|
const cli = new _eslint.CLIEngine(cliConfig);
|
|
let config;
|
|
|
|
if (filename || checkEslintrc) {
|
|
config = cli.getConfigForFile(file);
|
|
} // We need a new instance to ensure that the rules that may only
|
|
// be available to `file` (if it has its own `.eslintrc`),
|
|
// will be defined.
|
|
|
|
|
|
cliFile = new _eslint.CLIEngine({
|
|
allowInlineConfig,
|
|
baseConfig: { ...baseConfig,
|
|
...config
|
|
},
|
|
configFile,
|
|
reportUnusedDisableDirectives,
|
|
rulePaths,
|
|
rules,
|
|
useEslintrc: false
|
|
});
|
|
matchingFileNameMap.set(fileNameMapKey, cliFile);
|
|
}
|
|
|
|
const {
|
|
results: [{
|
|
messages
|
|
}]
|
|
} = cliFile.executeOnText(src); // NOTE: `tag.line` can be 0 if of form `/** @tag ... */`
|
|
|
|
const codeStartLine = tag.line + nonJSPrefacingLines;
|
|
const codeStartCol = likelyNestedJSDocIndentSpace;
|
|
messages.forEach(({
|
|
message,
|
|
line,
|
|
column,
|
|
severity,
|
|
ruleId
|
|
}) => {
|
|
const startLine = codeStartLine + line + zeroBasedLineIndexAdjust;
|
|
const startCol = codeStartCol + ( // This might not work for line 0, but line 0 is unlikely for examples
|
|
line <= 1 ? nonJSPrefacingCols + firstLinePrefixLength : preTagSpaceLength) + column;
|
|
report('@' + targetTagName + ' ' + (severity === 2 ? 'error' : 'warning') + (ruleId ? ' (' + ruleId + ')' : '') + ': ' + message, null, {
|
|
column: startCol,
|
|
line: startLine
|
|
});
|
|
});
|
|
};
|
|
|
|
sources.forEach(checkRules);
|
|
};
|
|
|
|
const getFilenameInfo = (filename, ext = 'md') => {
|
|
let defaultFileName;
|
|
|
|
if (!filename) {
|
|
const jsFileName = context.getFilename();
|
|
|
|
if (typeof jsFileName === 'string' && jsFileName.includes('.')) {
|
|
defaultFileName = jsFileName.replace(/\..*?$/, `.${ext}`);
|
|
} else {
|
|
defaultFileName = `dummy.${ext}`;
|
|
}
|
|
}
|
|
|
|
return {
|
|
defaultFileName,
|
|
filename
|
|
};
|
|
};
|
|
|
|
if (checkDefaults) {
|
|
const filenameInfo = getFilenameInfo(matchingFileNameDefaults, 'jsdoc-defaults');
|
|
utils.forEachPreferredTag('default', (tag, targetTagName) => {
|
|
if (!tag.description.trim()) {
|
|
return;
|
|
}
|
|
|
|
checkSource({
|
|
source: `(${tag.description})`,
|
|
targetTagName,
|
|
...filenameInfo
|
|
});
|
|
});
|
|
}
|
|
|
|
if (checkParams) {
|
|
const filenameInfo = getFilenameInfo(matchingFileNameParams, 'jsdoc-params');
|
|
utils.forEachPreferredTag('param', (tag, targetTagName) => {
|
|
if (!tag.default || !tag.default.trim()) {
|
|
return;
|
|
}
|
|
|
|
checkSource({
|
|
source: `(${tag.default})`,
|
|
targetTagName,
|
|
...filenameInfo
|
|
});
|
|
});
|
|
}
|
|
|
|
if (checkProperties) {
|
|
const filenameInfo = getFilenameInfo(matchingFileNameProperties, 'jsdoc-properties');
|
|
utils.forEachPreferredTag('property', (tag, targetTagName) => {
|
|
if (!tag.default || !tag.default.trim()) {
|
|
return;
|
|
}
|
|
|
|
checkSource({
|
|
source: `(${tag.default})`,
|
|
targetTagName,
|
|
...filenameInfo
|
|
});
|
|
});
|
|
}
|
|
|
|
const tagName = utils.getPreferredTagName({
|
|
tagName: 'example'
|
|
});
|
|
|
|
if (!utils.hasTag(tagName)) {
|
|
return;
|
|
}
|
|
|
|
const matchingFilenameInfo = getFilenameInfo(matchingFileName);
|
|
utils.forEachPreferredTag('example', (tag, targetTagName) => {
|
|
let source = tag.description;
|
|
const match = source.match(hasCaptionRegex);
|
|
|
|
if (captionRequired && (!match || !match[1].trim())) {
|
|
report('Caption is expected for examples.', null, tag);
|
|
} // If we allow newlines in hasCaptionRegex, we should add to line count
|
|
|
|
|
|
source = source.replace(hasCaptionRegex, '');
|
|
|
|
if (exampleCodeRegex && !exampleCodeRegex.test(source) || rejectExampleCodeRegex && rejectExampleCodeRegex.test(source)) {
|
|
return;
|
|
}
|
|
|
|
const sources = [];
|
|
let skipInit = false;
|
|
|
|
if (exampleCodeRegex) {
|
|
let nonJSPrefacingCols = 0;
|
|
let nonJSPrefacingLines = 0;
|
|
let startingIndex = 0;
|
|
let lastStringCount = 0;
|
|
let exampleCode;
|
|
exampleCodeRegex.lastIndex = 0;
|
|
|
|
while ((exampleCode = exampleCodeRegex.exec(source)) !== null) {
|
|
const {
|
|
index,
|
|
0: n0,
|
|
1: n1
|
|
} = exampleCode; // Count anything preceding user regex match (can affect line numbering)
|
|
|
|
const preMatch = source.slice(startingIndex, index);
|
|
const preMatchLines = countChars(preMatch, '\n');
|
|
const colDelta = preMatchLines ? preMatch.slice(preMatch.lastIndexOf('\n') + 1).length : preMatch.length;
|
|
let nonJSPreface;
|
|
let nonJSPrefaceLineCount;
|
|
|
|
if (n1) {
|
|
const idx = n0.indexOf(n1);
|
|
nonJSPreface = n0.slice(0, idx);
|
|
nonJSPrefaceLineCount = countChars(nonJSPreface, '\n');
|
|
} else {
|
|
nonJSPreface = '';
|
|
nonJSPrefaceLineCount = 0;
|
|
}
|
|
|
|
nonJSPrefacingLines += lastStringCount + preMatchLines + nonJSPrefaceLineCount; // Ignore `preMatch` delta if newlines here
|
|
|
|
if (nonJSPrefaceLineCount) {
|
|
const charsInLastLine = nonJSPreface.slice(nonJSPreface.lastIndexOf('\n') + 1).length;
|
|
nonJSPrefacingCols += charsInLastLine;
|
|
} else {
|
|
nonJSPrefacingCols += colDelta + nonJSPreface.length;
|
|
}
|
|
|
|
const string = n1 || n0;
|
|
sources.push({
|
|
nonJSPrefacingCols,
|
|
nonJSPrefacingLines,
|
|
string
|
|
});
|
|
startingIndex = exampleCodeRegex.lastIndex;
|
|
lastStringCount = countChars(string, '\n');
|
|
|
|
if (!exampleCodeRegex.global) {
|
|
break;
|
|
}
|
|
}
|
|
|
|
skipInit = true;
|
|
}
|
|
|
|
checkSource({
|
|
rules: mdRules,
|
|
skipInit,
|
|
source,
|
|
sources,
|
|
tag,
|
|
targetTagName,
|
|
...matchingFilenameInfo
|
|
});
|
|
});
|
|
}, {
|
|
iterateAllJsdocs: true,
|
|
meta: {
|
|
docs: {
|
|
description: 'Ensures that (JavaScript) examples within JSDoc adhere to ESLint rules.',
|
|
url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-examples'
|
|
},
|
|
schema: [{
|
|
additionalProperties: false,
|
|
properties: {
|
|
allowInlineConfig: {
|
|
default: true,
|
|
type: 'boolean'
|
|
},
|
|
baseConfig: {
|
|
type: 'object'
|
|
},
|
|
captionRequired: {
|
|
default: false,
|
|
type: 'boolean'
|
|
},
|
|
checkDefaults: {
|
|
default: false,
|
|
type: 'boolean'
|
|
},
|
|
checkEslintrc: {
|
|
default: true,
|
|
type: 'boolean'
|
|
},
|
|
checkParams: {
|
|
default: false,
|
|
type: 'boolean'
|
|
},
|
|
checkProperties: {
|
|
default: false,
|
|
type: 'boolean'
|
|
},
|
|
configFile: {
|
|
type: 'string'
|
|
},
|
|
exampleCodeRegex: {
|
|
type: 'string'
|
|
},
|
|
matchingFileName: {
|
|
type: 'string'
|
|
},
|
|
matchingFileNameDefaults: {
|
|
type: 'string'
|
|
},
|
|
matchingFileNameParams: {
|
|
type: 'string'
|
|
},
|
|
matchingFileNameProperties: {
|
|
type: 'string'
|
|
},
|
|
noDefaultExampleRules: {
|
|
default: false,
|
|
type: 'boolean'
|
|
},
|
|
paddedIndent: {
|
|
default: 0,
|
|
type: 'integer'
|
|
},
|
|
rejectExampleCodeRegex: {
|
|
type: 'string'
|
|
},
|
|
reportUnusedDisableDirectives: {
|
|
default: true,
|
|
type: 'boolean'
|
|
}
|
|
},
|
|
type: 'object'
|
|
}],
|
|
type: 'suggestion'
|
|
},
|
|
noTrim: true
|
|
});
|
|
|
|
exports.default = _default;
|
|
module.exports = exports.default;
|
|
//# sourceMappingURL=checkExamples.js.map
|