587 lines
No EOL
19 KiB
JavaScript
587 lines
No EOL
19 KiB
JavaScript
"use strict";
|
|
|
|
Object.defineProperty(exports, "__esModule", {
|
|
value: true
|
|
});
|
|
exports.getJsdocProcessorPlugin = void 0;
|
|
var _jsdocUtils = require("./jsdocUtils.cjs");
|
|
var _jsdoccomment = require("@es-joy/jsdoccomment");
|
|
var espree = _interopRequireWildcard(require("espree"));
|
|
var _htmlEntities = require("html-entities");
|
|
var _nodeFs = require("node:fs");
|
|
var _nodePath = require("node:path");
|
|
function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
|
|
/**
|
|
* @import {
|
|
* Integer,
|
|
* JsdocBlockWithInline,
|
|
* } from './iterateJsdoc.js';
|
|
* @import {
|
|
* ESLint,
|
|
* Linter,
|
|
* } from 'eslint';
|
|
*/
|
|
|
|
const {
|
|
version
|
|
} = JSON.parse((0, _nodeFs.readFileSync)((0, _nodePath.join)(__dirname, '../package.json'), 'utf8'));
|
|
|
|
// 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>([\s\S]*?)<\/caption>/v;
|
|
|
|
/**
|
|
* @param {string} str
|
|
* @returns {string}
|
|
*/
|
|
const escapeStringRegexp = str => {
|
|
return str.replaceAll(/[.*+?^$\{\}\(\)\|\[\]\\]/gv, '\\$&');
|
|
};
|
|
|
|
/**
|
|
* @param {string} str
|
|
* @param {string} ch
|
|
* @returns {Integer}
|
|
*/
|
|
const countChars = (str, ch) => {
|
|
return (str.match(new RegExp(escapeStringRegexp(ch), 'gv')) || []).length;
|
|
};
|
|
|
|
/**
|
|
* @param {string} text
|
|
* @returns {[
|
|
* Integer,
|
|
* Integer
|
|
* ]}
|
|
*/
|
|
const getLinesCols = text => {
|
|
const matchLines = countChars(text, '\n');
|
|
const colDelta = matchLines ? text.slice(text.lastIndexOf('\n') + 1).length : text.length;
|
|
return [matchLines, colDelta];
|
|
};
|
|
|
|
/**
|
|
* @typedef {number} Integer
|
|
*/
|
|
/**
|
|
* @typedef {object} JsdocProcessorOptions
|
|
* @property {boolean} [captionRequired] Require captions for example tags
|
|
* @property {Integer} [paddedIndent] See docs
|
|
* @property {boolean} [checkDefaults] See docs
|
|
* @property {boolean} [checkParams] See docs
|
|
* @property {boolean} [checkExamples] See docs
|
|
* @property {boolean} [checkProperties] See docs
|
|
* @property {string} [matchingFileName] See docs
|
|
* @property {string} [matchingFileNameDefaults] See docs
|
|
* @property {string} [matchingFileNameParams] See docs
|
|
* @property {string} [matchingFileNameProperties] See docs
|
|
* @property {string|RegExp} [exampleCodeRegex] See docs
|
|
* @property {string|RegExp} [rejectExampleCodeRegex] See docs
|
|
* @property {string[]} [allowedLanguagesToProcess] See docs
|
|
* @property {"script"|"module"} [sourceType] See docs
|
|
* @property {import('eslint').Linter.ESTreeParser|import('eslint').Linter.NonESTreeParser} [parser] See docs
|
|
*/
|
|
|
|
/**
|
|
* We use a function for the ability of the user to pass in a config, but
|
|
* without requiring all users of the plugin to do so.
|
|
* @param {JsdocProcessorOptions} [options]
|
|
* @returns {ESLint.Plugin}
|
|
*/
|
|
const getJsdocProcessorPlugin = (options = {}) => {
|
|
/**
|
|
* @typedef {{
|
|
* text: string,
|
|
* filename: string|null|undefined
|
|
* }} TextAndFileName
|
|
*/
|
|
|
|
const {
|
|
allowedLanguagesToProcess = ['js', 'ts', 'javascript', 'typescript'],
|
|
captionRequired = false,
|
|
checkDefaults = false,
|
|
checkExamples = true,
|
|
checkParams = false,
|
|
checkProperties = false,
|
|
exampleCodeRegex = null,
|
|
matchingFileName = null,
|
|
matchingFileNameDefaults = null,
|
|
matchingFileNameParams = null,
|
|
matchingFileNameProperties = null,
|
|
paddedIndent = 0,
|
|
parser = undefined,
|
|
rejectExampleCodeRegex = null,
|
|
sourceType = 'module'
|
|
} = options;
|
|
|
|
/** @type {RegExp} */
|
|
let exampleCodeRegExp;
|
|
/** @type {RegExp} */
|
|
let rejectExampleCodeRegExp;
|
|
if (exampleCodeRegex) {
|
|
exampleCodeRegExp = typeof exampleCodeRegex === 'string' ? (0, _jsdocUtils.getRegexFromString)(exampleCodeRegex) : exampleCodeRegex;
|
|
}
|
|
if (rejectExampleCodeRegex) {
|
|
rejectExampleCodeRegExp = typeof rejectExampleCodeRegex === 'string' ? (0, _jsdocUtils.getRegexFromString)(rejectExampleCodeRegex) : rejectExampleCodeRegex;
|
|
}
|
|
|
|
/**
|
|
* @type {{
|
|
* targetTagName: string,
|
|
* ext: string,
|
|
* codeStartLine: number,
|
|
* codeStartCol: number,
|
|
* nonJSPrefacingCols: number,
|
|
* commentLineCols: [number, number]
|
|
* }[]}
|
|
*/
|
|
const otherInfo = [];
|
|
|
|
/** @type {import('eslint').Linter.LintMessage[]} */
|
|
let extraMessages = [];
|
|
|
|
/**
|
|
* @param {JsdocBlockWithInline} jsdoc
|
|
* @param {string} jsFileName
|
|
* @param {[number, number]} commentLineCols
|
|
*/
|
|
const getTextsAndFileNames = (jsdoc, jsFileName, commentLineCols) => {
|
|
/**
|
|
* @type {TextAndFileName[]}
|
|
*/
|
|
const textsAndFileNames = [];
|
|
|
|
/**
|
|
* @param {{
|
|
* filename: string|null,
|
|
* defaultFileName: string|undefined,
|
|
* source: string,
|
|
* targetTagName: string,
|
|
* rules?: import('eslint').Linter.RulesRecord|undefined,
|
|
* lines?: Integer,
|
|
* cols?: Integer,
|
|
* skipInit?: boolean,
|
|
* ext: string,
|
|
* sources?: {
|
|
* nonJSPrefacingCols: Integer,
|
|
* nonJSPrefacingLines: Integer,
|
|
* string: string,
|
|
* }[],
|
|
* tag?: import('comment-parser').Spec & {
|
|
* line?: Integer,
|
|
* }|{
|
|
* line: Integer,
|
|
* }
|
|
* }} cfg
|
|
*/
|
|
const checkSource = ({
|
|
cols = 0,
|
|
defaultFileName,
|
|
ext,
|
|
filename,
|
|
lines = 0,
|
|
skipInit,
|
|
source,
|
|
sources = [],
|
|
tag = {
|
|
line: 0
|
|
},
|
|
targetTagName
|
|
}) => {
|
|
if (!skipInit) {
|
|
sources.push({
|
|
nonJSPrefacingCols: cols,
|
|
nonJSPrefacingLines: lines,
|
|
string: source
|
|
});
|
|
}
|
|
|
|
/**
|
|
* @param {{
|
|
* nonJSPrefacingCols: Integer,
|
|
* nonJSPrefacingLines: Integer,
|
|
* string: string
|
|
* }} cfg
|
|
*/
|
|
const addSourceInfo = function ({
|
|
nonJSPrefacingCols,
|
|
nonJSPrefacingLines,
|
|
string
|
|
}) {
|
|
const src = paddedIndent ? string.replaceAll(new RegExp(`(^|\n) {${paddedIndent}}(?!$)`, 'gv'), '\n') : string;
|
|
|
|
// Programmatic ESLint API: https://eslint.org/docs/developer-guide/nodejs-api
|
|
const file = filename || defaultFileName;
|
|
if (!('line' in tag)) {
|
|
tag.line = tag.source[0].number;
|
|
}
|
|
|
|
// NOTE: `tag.line` can be 0 if of form `/** @tag ... */`
|
|
const codeStartLine =
|
|
/**
|
|
* @type {import('comment-parser').Spec & {
|
|
* line: Integer,
|
|
* }}
|
|
*/
|
|
tag.line + nonJSPrefacingLines;
|
|
const codeStartCol = likelyNestedJSDocIndentSpace;
|
|
textsAndFileNames.push({
|
|
filename: file,
|
|
// See https://github.com/gajus/eslint-plugin-jsdoc/issues/710
|
|
text: src.replaceAll(/(?<=\*)\\(?=\\*\/)/gv, '').replaceAll(/&([^\s;]+);/gv, (_, code) => {
|
|
// Dec
|
|
if (/^#\d+$/v.test(code)) {
|
|
return String.fromCodePoint(Number.parseInt(code.slice(1), 10));
|
|
}
|
|
|
|
// Hex
|
|
if (/^#x\d+$/v.test(code)) {
|
|
return String.fromCodePoint(Number.parseInt(code.slice(2), 16));
|
|
}
|
|
return (0, _htmlEntities.decode)(_, {
|
|
level: 'html5'
|
|
});
|
|
})
|
|
});
|
|
otherInfo.push({
|
|
codeStartCol,
|
|
codeStartLine,
|
|
commentLineCols,
|
|
ext,
|
|
nonJSPrefacingCols,
|
|
targetTagName
|
|
});
|
|
};
|
|
for (const targetSource of sources) {
|
|
addSourceInfo(targetSource);
|
|
}
|
|
};
|
|
|
|
/**
|
|
*
|
|
* @param {string|null} filename
|
|
* @param {string} [ext] Since `eslint-plugin-markdown` v2, and
|
|
* ESLint 7, this is the default which other JS-fenced rules will used.
|
|
* Formerly "md" was the default.
|
|
* @returns {{
|
|
* defaultFileName: string|undefined,
|
|
* filename: string|null,
|
|
* ext: string
|
|
* }}
|
|
*/
|
|
const getFilenameInfo = (filename, ext = 'md/*.js') => {
|
|
let defaultFileName;
|
|
if (!filename) {
|
|
if (typeof jsFileName === 'string' && jsFileName.includes('.')) {
|
|
defaultFileName = jsFileName.replace(/\.[^.]*$/v, `.${ext}`);
|
|
} else {
|
|
defaultFileName = `dummy.${ext}`;
|
|
}
|
|
}
|
|
return {
|
|
defaultFileName,
|
|
ext,
|
|
filename
|
|
};
|
|
};
|
|
if (checkDefaults) {
|
|
const filenameInfo = getFilenameInfo(matchingFileNameDefaults, 'jsdoc-defaults');
|
|
(0, _jsdocUtils.forEachPreferredTag)(jsdoc, 'default', (tag, targetTagName) => {
|
|
if (!tag.description.trim()) {
|
|
return;
|
|
}
|
|
checkSource({
|
|
source: `(${(0, _jsdocUtils.getTagDescription)(tag)})`,
|
|
targetTagName,
|
|
...filenameInfo
|
|
});
|
|
});
|
|
}
|
|
if (checkParams) {
|
|
const filenameInfo = getFilenameInfo(matchingFileNameParams, 'jsdoc-params');
|
|
(0, _jsdocUtils.forEachPreferredTag)(jsdoc, 'param', (tag, targetTagName) => {
|
|
if (!tag.default || !tag.default.trim()) {
|
|
return;
|
|
}
|
|
checkSource({
|
|
source: `(${tag.default})`,
|
|
targetTagName,
|
|
...filenameInfo
|
|
});
|
|
});
|
|
}
|
|
if (checkProperties) {
|
|
const filenameInfo = getFilenameInfo(matchingFileNameProperties, 'jsdoc-properties');
|
|
(0, _jsdocUtils.forEachPreferredTag)(jsdoc, 'property', (tag, targetTagName) => {
|
|
if (!tag.default || !tag.default.trim()) {
|
|
return;
|
|
}
|
|
checkSource({
|
|
source: `(${tag.default})`,
|
|
targetTagName,
|
|
...filenameInfo
|
|
});
|
|
});
|
|
}
|
|
if (!checkExamples) {
|
|
return textsAndFileNames;
|
|
}
|
|
const tagName = /** @type {string} */(0, _jsdocUtils.getPreferredTagName)(jsdoc, {
|
|
tagName: 'example'
|
|
});
|
|
if (!(0, _jsdocUtils.hasTag)(jsdoc, tagName)) {
|
|
return textsAndFileNames;
|
|
}
|
|
const matchingFilenameInfo = getFilenameInfo(matchingFileName);
|
|
(0, _jsdocUtils.forEachPreferredTag)(jsdoc, 'example', (tag, targetTagName) => {
|
|
let source = /** @type {string} */(0, _jsdocUtils.getTagDescription)(tag);
|
|
const match = source.match(hasCaptionRegex);
|
|
if (captionRequired && (!match || !match[1].trim())) {
|
|
extraMessages.push({
|
|
column: commentLineCols[1] + 1,
|
|
line: 1 + commentLineCols[0] + (tag.line ?? tag.source[0].number),
|
|
message: `@${targetTagName} error - Caption is expected for examples.`,
|
|
ruleId: 'jsdoc/example-missing-caption',
|
|
severity: 2
|
|
});
|
|
return;
|
|
}
|
|
source = source.replace(hasCaptionRegex, '');
|
|
const [lines, cols] = match ? getLinesCols(match[0]) : [0, 0];
|
|
if (exampleCodeRegex && !exampleCodeRegExp.test(source) || rejectExampleCodeRegex && rejectExampleCodeRegExp.test(source)) {
|
|
return;
|
|
}
|
|
|
|
// If `allowedLanguagesToProcess` is falsy, all languages should be processed.
|
|
if (allowedLanguagesToProcess) {
|
|
const matches = /^\s*```(?<language>\S+)([\s\S]*)```\s*$/v.exec(source);
|
|
if (matches?.groups && !allowedLanguagesToProcess.includes(matches.groups.language.toLowerCase())) {
|
|
return;
|
|
}
|
|
}
|
|
const sources = [];
|
|
let skipInit = false;
|
|
if (exampleCodeRegex) {
|
|
let nonJSPrefacingCols = 0;
|
|
let nonJSPrefacingLines = 0;
|
|
let startingIndex = 0;
|
|
let lastStringCount = 0;
|
|
let exampleCode;
|
|
exampleCodeRegExp.lastIndex = 0;
|
|
while ((exampleCode = exampleCodeRegExp.exec(source)) !== null) {
|
|
const {
|
|
'0': n0,
|
|
'1': n1,
|
|
index
|
|
} = exampleCode;
|
|
|
|
// Count anything preceding user regex match (can affect line numbering)
|
|
const preMatch = source.slice(startingIndex, index);
|
|
const [preMatchLines, colDelta] = getLinesCols(preMatch);
|
|
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 = exampleCodeRegExp.lastIndex;
|
|
lastStringCount = countChars(string, '\n');
|
|
if (!exampleCodeRegExp.global) {
|
|
break;
|
|
}
|
|
}
|
|
skipInit = true;
|
|
}
|
|
checkSource({
|
|
cols,
|
|
lines,
|
|
skipInit,
|
|
source,
|
|
sources,
|
|
tag,
|
|
targetTagName,
|
|
...matchingFilenameInfo
|
|
});
|
|
});
|
|
return textsAndFileNames;
|
|
};
|
|
|
|
// See https://eslint.org/docs/latest/extend/plugins#processors-in-plugins
|
|
// See https://eslint.org/docs/latest/extend/custom-processors
|
|
// From https://github.com/eslint/eslint/issues/14745#issuecomment-869457265
|
|
/*
|
|
{
|
|
"files": ["*.js", "*.ts"],
|
|
"processor": "jsdoc/example" // a pretended value here
|
|
},
|
|
{
|
|
"files": [
|
|
"*.js/*_jsdoc-example.js",
|
|
"*.ts/*_jsdoc-example.js",
|
|
"*.js/*_jsdoc-example.ts"
|
|
],
|
|
"rules": {
|
|
// specific rules for examples in jsdoc only here
|
|
// And other rules for `.js` and `.ts` will also be enabled for them
|
|
}
|
|
}
|
|
*/
|
|
return {
|
|
meta: {
|
|
name: 'eslint-plugin-jsdoc/processor',
|
|
version
|
|
},
|
|
processors: {
|
|
examples: {
|
|
meta: {
|
|
name: 'eslint-plugin-jsdoc/preprocessor',
|
|
version
|
|
},
|
|
/**
|
|
* @param {import('eslint').Linter.LintMessage[][]} messages
|
|
* @param {string} filename
|
|
*/
|
|
postprocess([jsMessages, ...messages
|
|
// eslint-disable-next-line no-unused-vars -- Placeholder
|
|
], filename) {
|
|
for (const [idx, message] of messages.entries()) {
|
|
const {
|
|
codeStartCol,
|
|
codeStartLine,
|
|
commentLineCols,
|
|
nonJSPrefacingCols,
|
|
targetTagName
|
|
} = otherInfo[idx];
|
|
for (const msg of message) {
|
|
const {
|
|
column,
|
|
endColumn,
|
|
endLine,
|
|
fatal,
|
|
line,
|
|
message: messageText,
|
|
ruleId,
|
|
severity
|
|
|
|
// Todo: Make fixable
|
|
// fix
|
|
// fix: {range: [number, number], text: string}
|
|
// suggestions: {desc: , messageId:, fix: }[],
|
|
} = msg;
|
|
delete msg.fix;
|
|
const [codeCtxLine, codeCtxColumn] = commentLineCols;
|
|
const startLine = codeCtxLine + codeStartLine + line;
|
|
|
|
// Seems to need one more now
|
|
const startCol = 1 + codeCtxColumn + codeStartCol + (
|
|
// This might not work for line 0, but line 0 is unlikely for examples
|
|
line <= 1 ? nonJSPrefacingCols + firstLinePrefixLength : preTagSpaceLength) + column;
|
|
msg.message = '@' + targetTagName + ' ' + (severity === 2 ? 'error' : 'warning') + (ruleId ? ' (' + ruleId + ')' : '') + ': ' + (fatal ? 'Fatal: ' : '') + messageText;
|
|
msg.line = startLine;
|
|
msg.column = startCol;
|
|
msg.endLine = endLine ? startLine + endLine : startLine;
|
|
// added `- column` to offset what `endColumn` already seemed to include
|
|
msg.endColumn = endColumn ? startCol - column + endColumn : startCol;
|
|
}
|
|
}
|
|
const ret = [...jsMessages].concat(...messages, ...extraMessages);
|
|
extraMessages = [];
|
|
return ret;
|
|
},
|
|
/**
|
|
* @param {string} text
|
|
* @param {string} filename
|
|
* @returns {(string | Linter.ProcessorFile)[]}
|
|
*/
|
|
preprocess(text, filename) {
|
|
try {
|
|
let ast;
|
|
|
|
// May be running a second time so catch and ignore
|
|
try {
|
|
ast = parser ?
|
|
// @ts-expect-error Should be present
|
|
parser.parseForESLint(text, {
|
|
comment: true,
|
|
ecmaVersion: 'latest',
|
|
sourceType
|
|
}).ast : espree.parse(text, {
|
|
comment: true,
|
|
ecmaVersion: 'latest',
|
|
sourceType
|
|
});
|
|
} catch {
|
|
return [text];
|
|
}
|
|
|
|
/** @type {[number, number][]} */
|
|
const commentLineCols = [];
|
|
const jsdocComments = /** @type {import('estree').Comment[]} */(
|
|
/**
|
|
* @type {import('estree').Program & {
|
|
* comments?: import('estree').Comment[]
|
|
* }}
|
|
*/
|
|
ast.comments).filter(comment => {
|
|
return /^\*\s/v.test(comment.value);
|
|
}).map(comment => {
|
|
const [start
|
|
/* c8 ignore next -- Unsupporting processors only? */] = comment.range ?? [];
|
|
const textToStart = text.slice(0, start);
|
|
const [lines, cols] = getLinesCols(textToStart);
|
|
|
|
// const lines = [...textToStart.matchAll(/\n/gv)].length
|
|
// const lastLinePos = textToStart.lastIndexOf('\n');
|
|
// const cols = lastLinePos === -1
|
|
// ? 0
|
|
// : textToStart.slice(lastLinePos).length;
|
|
commentLineCols.push([lines, cols]);
|
|
return (0, _jsdoccomment.parseComment)(comment);
|
|
});
|
|
return [text, ...jsdocComments.flatMap((jsdoc, idx) => {
|
|
return getTextsAndFileNames(jsdoc, filename, commentLineCols[idx]);
|
|
}).filter(
|
|
/**
|
|
* @param {TextAndFileName} file
|
|
* @returns {file is Linter.ProcessorFile}
|
|
*/
|
|
file => {
|
|
return file !== null && file !== undefined;
|
|
})];
|
|
/* c8 ignore next 6 */
|
|
} catch (error) {
|
|
// eslint-disable-next-line no-console -- Debugging
|
|
console.log('err', filename, error);
|
|
}
|
|
return [];
|
|
},
|
|
supportsAutofix: true
|
|
}
|
|
}
|
|
};
|
|
};
|
|
exports.getJsdocProcessorPlugin = getJsdocProcessorPlugin;
|
|
//# sourceMappingURL=getJsdocProcessorPlugin.cjs.map
|