1 line
14 KiB
Plaintext
Executable file
1 line
14 KiB
Plaintext
Executable file
{"version":3,"sources":["../../src/rules/requireDescriptionCompleteSentence.js"],"names":["otherDescriptiveTags","Set","extractParagraphs","text","split","extractSentences","abbreviationsRegex","txt","replace","sentenceEndGrouping","puncts","map","punct","sentence","idx","test","isNewLinePrecededByAPeriod","lastLineEndsSentence","lines","some","line","isCapitalized","str","toUpperCase","isTable","charAt","capitalize","slice","validateDescription","description","reportOrig","jsdocNode","sourceCode","tag","newlineBeforeCapsAssumesBadSentenceEnd","paragraphs","paragraph","parIdx","sentences","fix","fixer","getText","_","last","RegExp","escapeRegExp","filter","sentence_","beginning","reg","_$0","$1","replaceText","report","msg","tagObj","column","paragraphNoAbbreviations","context","jsdoc","utils","options","abbreviations","length","abbreviation","join","tags","forEachPreferredTag","matchingJsdocTag","name","trim","tagsWithNames","getTagsByType","tagsWithoutNames","filterTags","tagName","has","hasOptionTag","trimStart","iterateAllJsdocs","meta","docs","url","fixable","schema","additionalProperties","properties","items","type"],"mappings":"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","sourcesContent":["import _ from 'lodash';\nimport {\n RegExtras,\n} from 'regextras/dist/main-umd';\nimport iterateJsdoc from '../iterateJsdoc';\n\nconst otherDescriptiveTags = new Set([\n // 'copyright' and 'see' might be good addition, but as the former may be\n // sensitive text, and the latter may have just a link, they are not\n // included by default\n 'summary', 'file', 'fileoverview', 'overview', 'classdesc', 'todo',\n 'deprecated', 'throws', 'exception', 'yields', 'yield',\n]);\n\nconst extractParagraphs = (text) => {\n return text.split(/(?<![;:])\\n\\n/u);\n};\n\nconst extractSentences = (text, abbreviationsRegex) => {\n const txt = text\n\n // Remove all {} tags.\n .replace(/\\{[\\s\\S]*?\\}\\s*/gu, '')\n\n // Remove custom abbreviations\n .replace(abbreviationsRegex, '');\n\n const sentenceEndGrouping = /([.?!])(?:\\s+|$)/u;\n const puncts = RegExtras(sentenceEndGrouping).map(txt, (punct) => {\n return punct;\n });\n\n return txt\n\n .split(/[.?!](?:\\s+|$)/u)\n\n // Re-add the dot.\n .map((sentence, idx) => {\n return /^\\s*$/u.test(sentence) ? sentence : `${sentence}${puncts[idx] || ''}`;\n });\n};\n\nconst isNewLinePrecededByAPeriod = (text) => {\n let lastLineEndsSentence;\n\n const lines = text.split('\\n');\n\n return !lines.some((line) => {\n if (lastLineEndsSentence === false && /^[A-Z][a-z]/u.test(line)) {\n return true;\n }\n\n lastLineEndsSentence = /[.:?!|]$/u.test(line);\n\n return false;\n });\n};\n\nconst isCapitalized = (str) => {\n return str[0] === str[0].toUpperCase();\n};\n\nconst isTable = (str) => {\n return str.charAt() === '|';\n};\n\nconst capitalize = (str) => {\n return str.charAt(0).toUpperCase() + str.slice(1);\n};\n\nconst validateDescription = (\n description, reportOrig, jsdocNode, abbreviationsRegex,\n sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd,\n) => {\n if (!description) {\n return false;\n }\n\n const paragraphs = extractParagraphs(description);\n\n return paragraphs.some((paragraph, parIdx) => {\n const sentences = extractSentences(paragraph, abbreviationsRegex);\n\n const fix = (fixer) => {\n let text = sourceCode.getText(jsdocNode);\n\n if (!/[.:?!]$/u.test(paragraph)) {\n const line = _.last(paragraph.split('\\n'));\n\n text = text.replace(new RegExp(`${_.escapeRegExp(line)}$`, 'mu'), `${line}.`);\n }\n\n for (const sentence of sentences.filter((sentence_) => {\n return !(/^\\s*$/u).test(sentence_) && !isCapitalized(sentence_) &&\n !isTable(sentence_);\n })) {\n const beginning = sentence.split('\\n')[0];\n\n if (tag.tag) {\n const reg = new RegExp(`(@${_.escapeRegExp(tag.tag)}.*)${_.escapeRegExp(beginning)}`, 'u');\n\n text = text.replace(reg, (_$0, $1) => {\n return $1 + capitalize(beginning);\n });\n } else {\n text = text.replace(new RegExp('((?:[.!?]|\\\\*|\\\\})\\\\s*)' + _.escapeRegExp(beginning), 'u'), '$1' + capitalize(beginning));\n }\n }\n\n return fixer.replaceText(jsdocNode, text);\n };\n\n const report = (msg, fixer, tagObj) => {\n tagObj.line += parIdx * 2;\n\n // Avoid errors if old column doesn't exist here\n tagObj.column = 0;\n reportOrig(msg, fixer, tagObj);\n };\n\n if (sentences.some((sentence) => {\n return !(/^\\s*$/u).test(sentence) && !isCapitalized(sentence) && !isTable(sentence);\n })) {\n report('Sentence should start with an uppercase character.', fix, tag);\n }\n\n const paragraphNoAbbreviations = paragraph.replace(abbreviationsRegex, '');\n\n if (!/[.!?|]$/u.test(paragraphNoAbbreviations)) {\n report('Sentence must end with a period.', fix, tag);\n\n return true;\n }\n\n if (newlineBeforeCapsAssumesBadSentenceEnd && !isNewLinePrecededByAPeriod(paragraphNoAbbreviations)) {\n report('A line of text is started with an uppercase character, but preceding line does not end the sentence.', null, tag);\n\n return true;\n }\n\n return false;\n });\n};\n\nexport default iterateJsdoc(({\n sourceCode,\n context,\n jsdoc,\n report,\n jsdocNode,\n utils,\n}) => {\n const options = context.options[0] || {};\n const {\n abbreviations = [],\n newlineBeforeCapsAssumesBadSentenceEnd = false,\n } = options;\n\n const abbreviationsRegex = abbreviations.length ?\n new RegExp('\\\\b' + abbreviations.map((abbreviation) => {\n return _.escapeRegExp(abbreviation.replace(/\\.$/g, '') + '.');\n }).join('|') + '(?:$|\\\\s)', 'gu') :\n '';\n\n if (!jsdoc.tags ||\n validateDescription(jsdoc.description, report, jsdocNode, abbreviationsRegex, sourceCode, {\n line: jsdoc.line + 1,\n }, newlineBeforeCapsAssumesBadSentenceEnd)\n ) {\n return;\n }\n\n utils.forEachPreferredTag('description', (matchingJsdocTag) => {\n const description = `${matchingJsdocTag.name} ${matchingJsdocTag.description}`.trim();\n validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, matchingJsdocTag, newlineBeforeCapsAssumesBadSentenceEnd);\n }, true);\n\n const {tagsWithNames} = utils.getTagsByType(jsdoc.tags);\n const tagsWithoutNames = utils.filterTags(({tag: tagName}) => {\n return otherDescriptiveTags.has(tagName) ||\n utils.hasOptionTag(tagName) && !tagsWithNames.some(({tag}) => {\n // If user accidentally adds tags with names (or like `returns`\n // get parsed as having names), do not add to this list\n return tag === tagName;\n });\n });\n\n tagsWithNames.some((tag) => {\n const description = _.trimStart(tag.description, '- ');\n\n return validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);\n });\n\n tagsWithoutNames.some((tag) => {\n const description = `${tag.name} ${tag.description}`.trim();\n\n return validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);\n });\n}, {\n iterateAllJsdocs: true,\n meta: {\n docs: {\n description: 'Requires that block description, explicit `@description`, and `@param`/`@returns` tag descriptions are written in complete sentences.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-description-complete-sentence',\n },\n fixable: 'code',\n schema: [\n {\n additionalProperties: false,\n properties: {\n abbreviations: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n newlineBeforeCapsAssumesBadSentenceEnd: {\n type: 'boolean',\n },\n tags: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"file":"requireDescriptionCompleteSentence.js"} |